Repository: pyro-ppl/numpyro

Issue:
NumPyro master and PyPI versions not in sync
Hi - I was running some examples that use newly released features on the master branch and noticed that the PyPI version seems to be based on the version 0.2.4 from January 2020.  I wonder if this is because the minor versions need to be incremented -- many new features have been added since January 2020, but the minor version has not been incremented.  Not sure how this package is updated on PyPI when there are updates to master.  Just wanted to surface this.


Discussion:
One reason the versioning may be important is that with the releases since January there are some backwards incompatibility issues if using the master branch (e.g., the SGT example). If someone downloads NumPyro from PyPI and then tries running the latest SGT - the example will fail at the imports.

```
ModuleNotFoundError: No module named 'numpyro.contrib.control_flow'
```
@jawolf314 Do you have some solutions for this issue? I understand your point but not sure what is the best way to deal with it.
Maybe we can add some pip statements at the first cell (like colab notebooks) which install the specific versions (if it is no longer backward compatibility) and remove it for each release?
I think when we move to using jax master for development, we could just bump up the version in `version.py` and checks in the examples / tutorials, i.e. our examples/tutorials on the master branch should assert that numpyro's version is at least `0.2.5`, and our `version.py` should be `0.2.5-dev`. That way the examples on the master branch will fail the assertion when run on an earlier version of jax/numpyro. Probably something to keep in mind after our release.
@fehiepsi I am not sure the best way to deal with this. I was wondering if there is CI/CD to PyPI when the new master branches are released - but based on the pip install numpyro the original 0.2.4 seems to be what is pulled from PyPI. I was wondering if incrementing the minor version when there are changes to master would be required - depending on how the deployment to PyPI is done.  I imagine many people are installing from PyPI instead of directly from the master branch in Github.
@fehiepsi, @neerajprad  Bumping up the micro version ("major.minor.micro" schema) when a change to master occurs would probably be the simplest solution.  Currently, the 0.2.4 in PyPI is incompatible with the time_series_forecast.ipynb, but the assert in that notebook is for version 0.2.4.  I took at look at PEP440 (https://www.python.org/dev/peps/pep-0440/#id24) - that's how I interpret the PEP.
Thanks @jawolf314! Let me ask some folks about the bumping micro version process. I'm not familiar with it.

The short term solution is we will try to fix #671 and release NumPyro 0.3 in a couple of days. But after that, I agree that tutorial requirement and numpyro version should be consistent so we should think about this issue after the release.


> Bumping up the micro version ("major.minor.micro" schema) when a change to master occurs would probably be the simplest solution.

That was my thought as well. As @fehiepsi mentioned, this will most likely not be an issue in the future until we start tracking jax master again after release, or make a backward incompatible change (which are becoming rarer). If we need to track the jax master again, we will make sure that we bump our version during development so that users are not misled. Thanks for raising this issue. 



@neerajprad Could you help me with this issue? It is unclear to me what we need to do. :(
@fehiepsi - From what I understood, the issue is that our version check in the tutorials is not as strict as it should be in the master branch. Anytime we are using something that is only available in the master branch in one of our tutorials, and a user runs the same tutorial with the release version of numpyro, we should raise an error. 

To address this, once we release `0.3.1`, we can bump up the version in `version.py` and prepend `dev` (`0.3.2-dev`) to it and update our checks in the tutorials. This is only relevant after the release (if we require our tutorials to use some feature from the master branch that's not in release) and I can do that once we make the next release. Feel free to remove the milestone, since this should happen after the release.
Thanks, @neerajprad! I get it now. That way makes a lot of sense to me.
@fehiepsi and @neerajprad , the initial reason I brought up the versioning was that in PyPI the package was behind the master branch in GitHub. I thought maybe this was due to the way the minor versioning was being handled in the package, because at the time the version in PyPI had the same major.minor.micro version number as the master branch in GitHub. The PyPI version was from January 2020. 
Sorry, @jawolf314! I missed your comment.

We use `master` branch for developing so it is not possible to pin `master` to PyPI. I know that some other repositories use `dev` for developing code and `master` for the released code but we don't follow that way here. To go to a PyPI version, you can use tag to find the correct code base. For example, code for `0.3.0` release can be found at [this link](https://github.com/pyro-ppl/numpyro/tree/0.3.0) or at [the example page](https://pyro.ai/numpyro/), which is updated after the release, hence in sync with PyPI version.

Resolving patch:
diff --git a/docs/source/conf.py b/docs/source/conf.py
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -65,6 +65,7 @@
     'nbsphinx',
     'sphinx.ext.autodoc',
     'sphinx.ext.doctest',
+    'sphinx.ext.imgconverter',
     'sphinx.ext.intersphinx',
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
@@ -138,6 +139,8 @@
 # This is processed by Jinja2 and inserted before each notebook
 nbsphinx_prolog = r"""
 {% set docname = 'notebooks/source/' + env.doc2path(env.docname, base=None).split('/')[-1] %}
+:github_url: https://github.com/pyro-ppl/numpyro/blob/master/{{ docname }}
+
 .. raw:: html
 
     <div class="admonition note">
@@ -193,6 +196,8 @@
     # only execute files beginning with plot_
     'filename_pattern': '/plot_',
     'ignore_pattern': '(minipyro|covtype|__init__)',
+    # not display Total running time of the script because we do not execute it
+    'min_reported_time': 1
 }
 
 
@@ -266,7 +271,10 @@
 
     # Additional stuff for the LaTeX preamble.
     #
-    # 'preamble': '',
+    'preamble': r'''
+        \usepackage{pmboxdraw}
+        \usepackage{alphabeta}
+        ''',
 
     # Latex figure (float) alignment
     #
diff --git a/examples/stochastic_volatility.py b/examples/stochastic_volatility.py
--- a/examples/stochastic_volatility.py
+++ b/examples/stochastic_volatility.py
@@ -7,7 +7,7 @@
 
 Generative model:
 
-.. math::
+.. math:: :nowrap:
 
     \\begin{align}
         \\sigma & \\sim \\text{Exponential}(50) \\\\


Test patch: