search

DHARPA-Project / kiara-website

Creative Commons Zero v1.0 Universal
0 stars 2 forks source link

Add a note for how and when to install a pre-release version of kiara #40

Open caro401 opened 6 months ago

caro401 commented 6 months ago

I'll write the information I think we need to include below, but leave it up to Petros or Cosimo to work out where this needs to live in the docs website and make better words. Initially I assumed this would go somewhere in internal/team-facing docs, but happy to be corrected for what makes most sense for the team.

Sometimes we need to use or test features from kiara when the version hasn't been published as a stable release yet. These releases are called "release candidates" or pre-releases, and will have a version number that looks like 0.5.10rc8 (with the rc bit at the end for release candidate). These versions get published to PyPI the same as standard versions of kiara, but pip won't install them for you by default because these versions aren't meant for the general public to use.

You can install pre-release versions with:

  • pip install --pre kiara to get the latest release even if it's a pre-release.
  • pip install kiara==0.5.10rc8 to get this specific pre-release version 0.5.10rc8.
  • pip install kiara@git+https://github.com/DHARPA-project/kiara.git@797957f6d27bd57dffe31dab18e89f77b1a6d25e to install the version of kiara at a specific git commit - the 797957... bit is the hash of the commit you want to install at

@makkus is there anything else end users need to know about using pre-release versions? A standard place to look for migration guides? You mentioned something about deleting contexts? Or perhaps that information is relevant to anyone upgrading their version of kiara and therefore needs to live somewhere else

makkus commented 6 months ago

This is the first pre-release version I've pushed to pypi, so we can make up rules for that if we want, I didn't really spend a lot of time thinking about it. This is the first time it came up, and a sort of special case because of the archive format being so central to kiara and the work I'd have to do to make it compatible after an upgrade (which I only want to do once -- hence not releasing until the format is fixed), I don't expect that to happen very often, if ever again. But could be wrong.

I'd assume that external users would not exposed to those pre-releases, normally? If there is a bug report and a (no-release) fix-release-candidate is pushed we could always tell specific users in that issue how to install and try it out in that issue? But I'm happy to adhere to any best practices if someone has an opion on any of that.

The deleting context thing is only relevant in this specific case, really. And once the next version of kiara is released, it should just work for anyone after a pip update, so no migration or so necessary, and hopefully we can keep it that way in the future as well.