# PyMC3 to PyMC Rename Guide
PyMC3 will be renamed to PyMC *October 1st*. What you'll need to do differs depending on how you use or interact with PyMC3. Use this guide to understand what that will be.

### Temporary metanote for PyMC Devs (as of late September)
By writing this migration guide first we'll have to enumerate all the things people will have to do, and by enumerating all the things that need to be done, we'll know what we will need to do.
And the good news is if we write this doc, once we know what to do it will already be documented. Neat huh

For now focus *only on the name change*. We can create another doc for the Aesara changes once we solidify those

## For new users
Nothing! Know that "PyMC3" is the old name of this probabilistic programming language (PPL) and that "PyMC" will be used henceforth.

If you want to work with a "3.x.x" version, you'll have to install the "pymc3" package from PyPI or conda forge.

## For existing end users
The most important thing to understand is that PyMC will refer to a version of the PPL that uses Aesara as its backend. You still will be able to install and use PyMC3, it just wont be updated and support will drop over time.

If you're a current PyMC3 end user to upgrade you will need to

* uninstall pymc3 from your environment and install pymc using one of the methods below
* pip install pymc
* conda install pymc
* git clone etc etc

* Change your imports from `import pymc3 as pm` to `import pymc as pm`

## If you want to use V4
***⚠️ TO DO***

## If you're a PyMC3 developer
The PyMC3 repo has been named to PyMC. If you need the PyMC3 codebase

### Proposal 1
Copy the codebase at v3 commit to another repo called PyMC3 legacy

### Proposal 2

***⚠️ TO DO?***

## For package maintainers of libraries that use PyMC3
You will need to

* Change your imports from `import pymc3 as pm` to `import pymc as pm`
* Change your documentation to refer to PyMC
* Preferably change your git origin and github links from https://github.com/pymc-devs/pymc3 to https://github.com/pymc-devs/pymc (Note that the old one will forward automatically, but that might be confusing.)
* Update the Zenodo record with the new name
* Reconfigure Read The Docs to the new url and set up forwarding from the old one.

## For PyMC Devs
You will need to
* Change your imports from `import pymc3 as pm` to `import pymc as pm`
* Find and replace PyMC3 mentions in the codebase and documentation (pymc-example).
* Update the logos in repository
* Change the pypi package name to pymc (MO: is that even possible??)
* Find out how to deal with the existing https://github.com/pymc-devs/pymc Repository. This probably results in problems with the HTTP 301 forwarding
* Diplomatically approach and tell PyMC v2 users that we're taking over their existing PyPI channel and they should upgrade or pin version numbers. And that their repOS are in the way.
* Replace or update https://github.com/conda-forge/pymc-feedstock
* Update all documentation to reflect PyMC, including example guides
* Rename the Wikipedia page and add an explanation there https://en.wikipedia.org/wiki/PyMC3

## For NumFOCUS
You will need to
* Review any legal or financial documents that may refer to this team by the PyMC3 name and update those to PyMC
* Update PyMC logo on website
* Update logo merchandise stores
* Give away remaining stickers

# Rename schema

### What to do with old PyMC repo

#### Rename current PyMC repo (2.x) to PyMC2/PyMC_old

This way we make room for the other repo. Alternatively, we could port PyMC v2 to a branch on our existing repo, but I (TW) don't think that would be all that helpful.

Note that this change is unrelated to what we name the package on PyPI and

### Rename the current repo AND make a copy of it at the PyMC3 V3 commit and name that repo to pymc3_v3
In addition to renaming we need to

* Add a warning to README.md that users should only use this repo if they specifically want PyMC3
* Migrate all pull requests and relevant issues to the legacy repo

Pros:
* One clean cut
* Maintain GitHub stars etc
* History is maintained
* Allows for autoforwarding
* It provides another place to message the name change
* If downstream devs want to specify github builds itll be more obvious in the repo string

Cons:
* Two repos with similar codebase, at least initially

### What to do with v3 on PyPI and conda-forge?

#### Keep it as pymc3 on PyPI and conda-forge

Pros:
* v3 users have an easier time staying on v3 because they do not need to change anything and do not need to pin versions so as not to get v4
* Users have to be explicit about upgrading to v4
* This makes it easy for our conda-forge feedstock because we have changed the dependencies (`theano-pymc` to `aesara`)

Cons:
* Users might not know about the rename and will just stick to PyMC3, thus requires strong messaging.

## The current plan on what to do about repo and PyPI and conda-forge

In summary, v3 will stay pymc3 on pypi and conda-forge, from v4 onwards it will be pymc on both.

1. Move current PyMC v2 repo to PyMC2 just to make room.
2. Rename the PyMC3 repo to PyMC and get forwarding.
3. On PyMC PyPI we make a release only for 4.x. We keep PyMC3 on PyPI, that is a reasonable way to remain backwards compatibility and not break people's production systems.
4. Once we are ready with v4, we release pymc 4.0.0, as well as pymc3 3.11.5 with an import warning alerting people to the name change and new version, as well as deprecation warnings for things like `pm.Normal.logp`.