| Name | chronver JSON |
| Version |
20240318.230216
JSON |
| download |
| home_page | |
| Summary | Setuptools plugin for chronological versions from Git |
| upload_time | 2024-03-18 23:21:02 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | |
| keywords |
git
plugin
scm
setuptools
vcs
version
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
## Introduction
ChronVer is a
[setuptools.meta_build](https://setuptools.pypa.io/en/latest/build_meta.html)
plugin to add a
[chronological version](https://www.robnagler.com/2015/04/11/Major-Release-Syndrome.html)
(yyyymmdd.hhmmss)
to a Python package's metadata from the current Git commit of `HEAD`.
This ensures a unique, sortable version for packages on [PyPI](https://pypi.org).
In development, if there are modifications, the current time will be
returned. This ensures that `pip install` works, because there's
always a new, increasing version.
## Usage
Add this to your `pyproject.toml`:
```toml
[build-system]
requires = ["setuptools>=61", "chronver"]
build-backend = "setuptools.build_meta"
[project]
dynamic = ["version"]
```
If you are using Python 3.8 or above, include this code in your
``<your_package>.__init__.py``:
```py
import importlib.metadata
try:
__version__ = importlib.metadata.version("your_package")
except importlib.metadata.PackageNotFoundError:
# A package only has a version once it has been built or installed.
# By not defining __version__, clients will fail fast if they
# require __version__ (unlikely).
pass
```
If you are using a Python before 3.8, use the backport
[`importlib_metadata`](https://importlib-metadata.readthedocs.io).
## Releases without breakage (almost)
[RadiaSoft](https://radiasoft.net) uses chronological versioning for
all its releases. This means no major releases, which implies breaking
changes. To make this happen, we strive to maintain backward
compatibility for as long as our users require it.
This is why there are no major or minor release numbers in
chronological versions; there are no breaking API changes (except
defects, of course) with each release. We feel it is our obligation to
not break our client's code.
There are times when this is impossible or impractical, such as the
move away from Python 2. In those cases, we give clients warnings and
an upgrade path and sometimes a tool that upgrades their data or code
automatically. This is an obligation that comes with chronological
versioning that RadiaSoft takes seriously.
## Why another versioning scheme?
ChronVer is a new implementation of our existing
[setup.py versioning module](https://github.com/radiasoft/pykern/blob/eaea8492e1e8485c8b35aee67ad1204e8838da97/pykern/pksetup.py#L684)
so it is not new at all. RadiaSoft has been using chronological
versioning for Python, Docker images, packaging (RPMs), etc. for over
a decade. Before that @robnagler (primary author) was using
chronlogical versioning since at least 2000. So there's a long history
here, and it has worked well for us.
[SemVer](https://semver.org) makes many assumptions about how software
works that conflicts with how we develop. In our model, software flows
like time, and releases are arbitary points on the time axis. SemVer
divides software releases into fixed epochs: major, minor, patch, and
additional labels. This requires people make complicated decisions
about these different kinds of epochs, which adds work and we think
adds little value. This can result in
[Major Release Syndrome](https://www.robnagler.com/2015/04/11/Major-Release-Syndrome.html),
which is an impediment to continuous software development and
deployment.
[CalVer](https://calver.org) has a great tag line: "Versioning gets
better with time." We agree! In CalVer, "time" means "date", that is,
days are the time quantum. This granularity does not allow for same
day releases, which we happen to do on occasion. A second is
ChronVer's time quantum for this reason. CalVer tries to be SemVer
compliant, which as noted above, is not how we develop software.
There are benefits to simplifying version strings to always being
lexicographically sortable. Any two ChronVers can be compared with a
single operator `v1 < v2`. We have a lot internal devops tooling in
multiple languages, and all languages support simple lexicographic
comparison of strings. A ChronVer is compatible with Python's `float`,
which is useful in some cases.
A ChronVer identifies any commit in any SCM. We use Git now. We used
to use CVS (which does not have a SHA), and ChronVer worked just as
well. All SCM's (that we know of) answer the question: what was the
commit at this timestamp? SemVer and CalVer have various schemes for
doing this, but they are awkward and break lexicographic comparison.
For more complete reasoning, refer to
[Major Release Syndrome](https://www.robnagler.com/2015/04/11/Major-Release-Syndrome.html).
Raw data
{
"_id": null,
"home_page": "",
"name": "chronver",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "git,plugin,scm,setuptools,vcs,version",
"author": "",
"author_email": "RadiaSoft LLC <pip@pykern.org>",
"download_url": "https://files.pythonhosted.org/packages/d3/80/ca71ea44ad96f5abf5a2e95f8b34439ab43ddb293e2cc517679794b8f9eb/chronver-20240318.230216.tar.gz",
"platform": null,
"description": "## Introduction\n\nChronVer is a\n[setuptools.meta_build](https://setuptools.pypa.io/en/latest/build_meta.html)\nplugin to add a\n[chronological version](https://www.robnagler.com/2015/04/11/Major-Release-Syndrome.html)\n(yyyymmdd.hhmmss)\nto a Python package's metadata from the current Git commit of `HEAD`.\nThis ensures a unique, sortable version for packages on [PyPI](https://pypi.org).\n\nIn development, if there are modifications, the current time will be\nreturned. This ensures that `pip install` works, because there's\nalways a new, increasing version.\n\n## Usage\n\nAdd this to your `pyproject.toml`:\n\n```toml\n[build-system]\nrequires = [\"setuptools>=61\", \"chronver\"]\nbuild-backend = \"setuptools.build_meta\"\n\n[project]\ndynamic = [\"version\"]\n```\n\nIf you are using Python 3.8 or above, include this code in your\n``<your_package>.__init__.py``:\n\n```py\nimport importlib.metadata\n\ntry:\n __version__ = importlib.metadata.version(\"your_package\")\nexcept importlib.metadata.PackageNotFoundError:\n # A package only has a version once it has been built or installed.\n # By not defining __version__, clients will fail fast if they\n # require __version__ (unlikely).\n pass\n```\n\nIf you are using a Python before 3.8, use the backport\n[`importlib_metadata`](https://importlib-metadata.readthedocs.io).\n\n## Releases without breakage (almost)\n\n[RadiaSoft](https://radiasoft.net) uses chronological versioning for\nall its releases. This means no major releases, which implies breaking\nchanges. To make this happen, we strive to maintain backward\ncompatibility for as long as our users require it.\n\nThis is why there are no major or minor release numbers in\nchronological versions; there are no breaking API changes (except\ndefects, of course) with each release. We feel it is our obligation to\nnot break our client's code.\n\nThere are times when this is impossible or impractical, such as the\nmove away from Python 2. In those cases, we give clients warnings and\nan upgrade path and sometimes a tool that upgrades their data or code\nautomatically. This is an obligation that comes with chronological\nversioning that RadiaSoft takes seriously.\n\n## Why another versioning scheme?\n\nChronVer is a new implementation of our existing\n[setup.py versioning module](https://github.com/radiasoft/pykern/blob/eaea8492e1e8485c8b35aee67ad1204e8838da97/pykern/pksetup.py#L684)\nso it is not new at all. RadiaSoft has been using chronological\nversioning for Python, Docker images, packaging (RPMs), etc. for over\na decade. Before that @robnagler (primary author) was using\nchronlogical versioning since at least 2000. So there's a long history\nhere, and it has worked well for us.\n\n[SemVer](https://semver.org) makes many assumptions about how software\nworks that conflicts with how we develop. In our model, software flows\nlike time, and releases are arbitary points on the time axis. SemVer\ndivides software releases into fixed epochs: major, minor, patch, and\nadditional labels. This requires people make complicated decisions\nabout these different kinds of epochs, which adds work and we think\nadds little value. This can result in\n[Major Release Syndrome](https://www.robnagler.com/2015/04/11/Major-Release-Syndrome.html),\nwhich is an impediment to continuous software development and\ndeployment.\n\n[CalVer](https://calver.org) has a great tag line: \"Versioning gets\nbetter with time.\" We agree! In CalVer, \"time\" means \"date\", that is,\ndays are the time quantum. This granularity does not allow for same\nday releases, which we happen to do on occasion. A second is\nChronVer's time quantum for this reason. CalVer tries to be SemVer\ncompliant, which as noted above, is not how we develop software.\n\nThere are benefits to simplifying version strings to always being\nlexicographically sortable. Any two ChronVers can be compared with a\nsingle operator `v1 < v2`. We have a lot internal devops tooling in\nmultiple languages, and all languages support simple lexicographic\ncomparison of strings. A ChronVer is compatible with Python's `float`,\nwhich is useful in some cases.\n\nA ChronVer identifies any commit in any SCM. We use Git now. We used\nto use CVS (which does not have a SHA), and ChronVer worked just as\nwell. All SCM's (that we know of) answer the question: what was the\ncommit at this timestamp? SemVer and CalVer have various schemes for\ndoing this, but they are awkward and break lexicographic comparison.\n\nFor more complete reasoning, refer to\n[Major Release Syndrome](https://www.robnagler.com/2015/04/11/Major-Release-Syndrome.html).\n",
"bugtrack_url": null,
"license": "",
"summary": "Setuptools plugin for chronological versions from Git",
"version": "20240318.230216",
"project_urls": {
"Homepage": "https://github.com/radiasoft/chronver"
},
"split_keywords": [
"git",
"plugin",
"scm",
"setuptools",
"vcs",
"version"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "60c46b65465cc3a3fa1cb9fb8d81ee1bb790eeee685b718c78daecc309c4ddfc",
"md5": "f98fdba73281ff1ca1efdee214d4e05a",
"sha256": "fca8d702b6c908b62b01c28a33cf9677b2e0ee94857ec4f5d58fd56f849a7958"
},
"downloads": -1,
"filename": "chronver-20240318.230216-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f98fdba73281ff1ca1efdee214d4e05a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 10717,
"upload_time": "2024-03-18T23:21:00",
"upload_time_iso_8601": "2024-03-18T23:21:00.773834Z",
"url": "https://files.pythonhosted.org/packages/60/c4/6b65465cc3a3fa1cb9fb8d81ee1bb790eeee685b718c78daecc309c4ddfc/chronver-20240318.230216-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d380ca71ea44ad96f5abf5a2e95f8b34439ab43ddb293e2cc517679794b8f9eb",
"md5": "acaf227d57d50e7c279cf62e2282c1ff",
"sha256": "ddfb2aaca3d0d871657d6a5a4ced37368694c1e0a542e425f61149d663a730aa"
},
"downloads": -1,
"filename": "chronver-20240318.230216.tar.gz",
"has_sig": false,
"md5_digest": "acaf227d57d50e7c279cf62e2282c1ff",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 11473,
"upload_time": "2024-03-18T23:21:02",
"upload_time_iso_8601": "2024-03-18T23:21:02.820656Z",
"url": "https://files.pythonhosted.org/packages/d3/80/ca71ea44ad96f5abf5a2e95f8b34439ab43ddb293e2cc517679794b8f9eb/chronver-20240318.230216.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-18 23:21:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "radiasoft",
"github_project": "chronver",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "chronver"
}
