Semantic Version v2.0.0 Specification (#1569)

<!--Please ensure the PR fulfills the following requirements! -->
<!-- If this is your first PR, make sure to add your details to the
AUTHORS.rst! -->
### Pull Request Checklist:
- [x] This PR addresses an already opened issue (for bug fixes /
features)
    - This PR fixes #1556 and fixes #1557 
- [ ] Tests for the changes have been added (for bug fixes / features)
- [ ] (If applicable) Documentation has been added / updated (for bug
fixes / features)
- [x] CHANGES.rst has been updated (with summary of main changes)
- [x] Link to issue (:issue:`number`) and pull request (:pull:`number`)
has been added

### What kind of change does this PR introduce?

* `xclim` now adheres to the [Semantic Versioning
2.0.0](https://semver.org/) specification.
* `bump2version` has been replaced with `bump-my-version`
* The `setup.cfg` has been deleted; `flake8` configurations have
migrated to `.flake8` file, and `bumpversion` configuration is now found
in `pyproject.toml`.
* Fixed an issue with the `.gitignore` to properly ignore some
autogenerated files.

### Does this PR introduce a breaking change?

Yes. The versioning system has been adjusted so that patch versions are
not augmented at every push to `xclim` code; instead, the build version
is adjusted.

### Other information:

https://callowayproject.github.io/bump-my-version/

.flake8

@@ -0,0 +1,40 @@
+[flake8]
+exclude =
+	.git,
+	docs,
+	build,
+	.eggs,
+	tests
+ignore =
+	AZ100,
+	AZ200,
+	AZ300,
+	C,
+	D,
+	E,
+	F,
+	W503
+per-file-ignores =
+	xclim/core/locales.py:RST399
+rst-directives =
+	bibliography,
+	autolink-skip
+rst-roles =
+	doc,
+	mod,
+	py:attr,
+	py:attribute,
+	py:class,
+	py:const,
+	py:data,
+	py:func,
+	py:indicator,
+	py:meth,
+	py:mod,
+	py:obj,
+	py:ref,
+	ref,
+	cite:cts,
+	cite:p,
+	cite:t,
+	cite:ts

.github/workflows/bump-version.yml

@@ -20,7 +20,6 @@ on:
       - pyproject.toml
       - requirements_dev.txt
       - requirements_upstream.txt
-      - setup.cfg
       - tox.ini
       - xclim/__init__.py
 
@@ -43,10 +42,22 @@ jobs:
         run: |
           CURRENT_VERSION="$(grep -E '__version__'  xclim/__init__.py | cut -d ' ' -f3)"
           echo "current_version=${CURRENT_VERSION}"
+          echo "CURRENT_VERSION=${CURRENT_VERSION}" >> $GITHUB_ENV
+      - name: Install bump-my-version
+        run: |
+          python -m pip install bump-my-version
       - name: Bump Patch Version
+        if: ${{ !env.CURRENT_VERSION =~ \d+\.\d+\.\d+(-dev(\.\d+)?)?$ }}
+        run: |
+          echo "Version is stable, bumping 'patch' version"
+          bump-my-version bump patch
+          NEW_VERSION="$(grep -E '__version__'  xclim/__init__.py | cut -d ' ' -f3)"
+          echo "new_version=${NEW_VERSION}"
+      - name: Bump Build Version
+        if: ${{ env.CURRENT_VERSION =~ \d+\.\d+\.\d+(-dev(\.\d+)?)?$ }}
         run: |
-          python -m pip install bump2version
-          echo "running `bump2version patch`"
+          echo "Development version (ends in 'dev(\.\d+)?'), bumping 'build' version"
+          bump-my-version bump build
           NEW_VERSION="$(grep -E '__version__'  xclim/__init__.py | cut -d ' ' -f3)"
           echo "new_version=${NEW_VERSION}"
       - name: Push Changes

.github/workflows/codeql-analysis.yml

@@ -9,7 +9,6 @@ on:
       - Makefile
       - pyproject.toml
       - requirements_upstream.txt
-      - setup.cfg
       - tox.ini
       - xclim/__init__.py
       - docs/**.ipynb

.github/workflows/main.yml

@@ -8,7 +8,6 @@ on:
       - CHANGES.rst
       - README.rst
       - pyproject.toml
-      - setup.cfg
       - xclim/__init__.py
   pull_request:
     types:

.github/workflows/upstream.yml

@@ -7,7 +7,6 @@ on:
       - CHANGES.rst
       - README.rst
       - pyproject.toml
-      - setup.cfg
       - xclim/__init__.py
   schedule:
     - cron: "0 0 * * *" # Daily “At 00:00” UTC

.gitignore

@@ -107,23 +107,10 @@ ENV/
 .idea/
 
 # autogenerated RestructuredText
-/docs/modules.rst
-/docs/xclim.core.rst
-/docs/xclim.data.rst
-/docs/xclim.ensembles.rst
-/docs/xclim.indicators.atmos.rst
-/docs/xclim.indicators.generic.rst
-/docs/xclim.indicators.land.rst
-/docs/xclim.indicators.rst
-/docs/xclim.indicators.seaIce.rst
-/docs/xclim.indices.fire.rst
-/docs/xclim.indices.rst
-/docs/xclim.locales.rst
-/docs/xclim.rst
-/docs/xclim.sdba.rst
-/docs/xclim.testing.rst
-/docs/xclim.testing.tests.rst
-/docs/xclim.testing.tests.test_sdba.rst
+docs/apidoc/modules.rst
+docs/apidoc/xclim*.rst
+docs/indicators.json
+docs/variables.json
 
 .vscode
 

.pre-commit-config.yaml

@@ -12,7 +12,6 @@ repos:
   rev: v4.5.0
   hooks:
   - id: trailing-whitespace
-    exclude: setup.cfg
   - id: end-of-file-fixer
     exclude: '.ipynb|.github/publish-mastodon.template.md'
   - id: check-json
@@ -33,28 +32,28 @@ repos:
   - id: yamllint
     args: [ '--config-file=.yamllint.yaml' ]
 - repo: https://github.com/psf/black-pre-commit-mirror
-  rev: 23.11.0
+  rev: 23.12.0
   hooks:
   - id: black
 - repo: https://github.com/PyCQA/isort
-  rev: 5.12.0
+  rev: 5.13.2
   hooks:
   - id: isort
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.1.6
+  rev: v0.1.9
   hooks:
   - id: ruff
 - repo: https://github.com/pycqa/flake8
   rev: 6.1.0
   hooks:
   - id: flake8
     additional_dependencies: [ 'flake8-alphabetize', 'flake8-rst-docstrings ']
-    args: [ '--config=setup.cfg' ]
+    args: [ '--config=.flake8' ]
 - repo: https://github.com/nbQA-dev/nbQA
   rev: 1.7.1
   hooks:
   - id: nbqa-black
-    additional_dependencies: [ 'black==23.11.0' ]
+    additional_dependencies: [ 'black==23.12.0' ]
   - id: nbqa-pyupgrade
     args: [ '--py38-plus' ]
   - id: nbqa-isort
@@ -69,9 +68,9 @@ repos:
   hooks:
   - id: blackdoc
     exclude: '(xclim/indices/__init__.py|docs/installation.rst)'
-    additional_dependencies: [ 'black==23.11.0' ]
+    additional_dependencies: [ 'black==23.12.0' ]
 - repo: https://github.com/python-jsonschema/check-jsonschema
-  rev: 0.27.2
+  rev: 0.27.3
   hooks:
   - id: check-github-workflows
   - id: check-readthedocs

CHANGES.rst

@@ -6,16 +6,29 @@ v0.48 (unreleased)
 ------------------
 Contributors to this version: Juliette Lavoie (:user:`juliettelavoie`), Pascal Bourgault (:user:`aulemahal`), Trevor James Smith (:user:`Zeitsperre`), David Huard (:user:`huard`), Éric Dupuis (:user:`coxipi`).
 
+Announcements
+^^^^^^^^^^^^^
+* `xclim` now adheres to the `Semantic Versioning 2.0.0 <https://semver.org/>`_ specification. (:issue:`1556`, :pull:`1569`).
+
 New features and enhancements
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 * Added uncertainty partitioning method `lafferty_sriver` from Lafferty and Sriver (2023), which can partition uncertainty related to the downscaling method. (:issue:`1497`, :pull:`1529`).
 * Validate YAML indicators description before trying to build module. (:issue:`1523`, :pull:`1560`).
 * New ``xclim.core.calendar.stack_periods`` and ``unstack_periods`` for performing ``rolling(time=...).construct(..., stride=...)`` but with non-uniform temporal periods like years or months. They replace ``xclim.sdba.processing.construct_moving_yearly_window`` and ``unpack_moving_yearly_window`` which are deprecated and will be removed in a future release.
 
+Breaking changes
+^^^^^^^^^^^^^^^^
+* `bump2version` has been replaced with `bump-my-version` to bump the version number using configurations set in the `pyproject.toml` file. (:issue:`1557`, :pull:`1569`).
+
 Bug fixes
 ^^^^^^^^^
 * Fixed passing ``missing=0`` to ``xclim.core.calendar.convert_calendar`` (:issue:`1562`, :pull:`1563`).
 
+Internal changes
+^^^^^^^^^^^^^^^^
+* The `flake8` configuration has been migrated from `setup.cfg` to `.flake8`; `setup.cfg` has been removed. (:pull:`1569`)
+* The `bump-version.yml` workflow has been adjusted to bump the `patch` version when the last version is determined to have been a `release` version; otherwise, the `build` version is bumped. (:issue:`1557`, :pull:`1569`).
+
 v0.47.0 (2023-12-01)
 --------------------
 Contributors to this version: Juliette Lavoie (:user:`juliettelavoie`), Pascal Bourgault (:user:`aulemahal`), Trevor James Smith (:user:`Zeitsperre`), David Huard (:user:`huard`), Éric Dupuis (:user:`coxipi`).

CONTRIBUTING.rst

@@ -147,7 +147,7 @@ Ready to contribute? Here's how to set up `xclim` for local development.
 	$ black --check xclim tests
 	$ isort --check xclim tests
 	$ ruff xclim tests
-	$ flake8 --config=setup.cfg xclim tests
+	$ flake8 --config=.flake8 xclim tests
 	$ nbqa black --check docs
 	$ nbqa isort --check docs
 	$ blackdoc --check --exclude=xclim/indices/__init__.py xclim

Makefile

@@ -56,7 +56,7 @@ lint: ## check style with flake8 and black
 	black --check xclim tests
 	isort --check xclim tests
 	ruff xclim tests
-	flake8 --config=setup.cfg xclim tests
+	flake8 --config=.flake8 xclim tests
 	nbqa black --check docs
 	blackdoc --check --exclude=xclim/indices/__init__.py xclim
 	blackdoc --check docs

environment.yml

@@ -30,7 +30,7 @@ dependencies:
   # Testing and development dependencies
     - black >=22.12
     - blackdoc
-    - bump2version
+    - bump-my-version
     - cairosvg
     - coverage
     - distributed >=2.0

pyproject.toml

@@ -59,7 +59,7 @@ dev = [
   # Dev tools and testing
   "black >=23.3.0",
   "blackdoc",
-  "bump2version",
+  "bump-my-version",
   "coverage[toml]",
   "flake8",
   "flake8-alphabetize",
@@ -121,6 +121,32 @@ target-version = [
   "py311"
 ]
 
+[tool.bumpversion]
+current_version = "0.47.4-beta"
+commit = true
+tag = false
+allow_dirty = true
+parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)(\\-(?P<release>[a-z]+)(\\.(?P<build>\\d+)))?"
+serialize = [
+  "{major}.{minor}.{patch}-{release}.{build}",
+  "{major}.{minor}.{patch}"
+]
+
+[[tool.bumpversion.files]]
+filename = "xclim/__init__.py"
+search = "__version__ = \"{current_version}\""
+replace = "__version__ = \"{new_version}\""
+
+[tool.bumpversion.parts.build]
+independent = false
+
+[tool.bumpversion.parts.release]
+optional_value = "release"
+values = [
+  "dev",
+  "release"
+]
+
 [tool.coverage.run]
 relative_files = true
 omit = ["tests/*.py"]
@@ -143,7 +169,6 @@ include = [
   "docs/make.bat",
   "docs/notebooks/_finder.py",
   "requirements_upstream.txt",
-  "setup.cfg",
   "tests/**/*.py",
   "tests/**/*.txt",
   "tox.ini",

tox.ini

@@ -34,7 +34,7 @@ commands =
     black --check xclim tests
     isort --check xclim tests
     ruff xclim tests
-    flake8 --config=setup.cfg xclim tests
+    flake8 --config=.flake8 xclim tests
     nbqa black --check docs
     blackdoc --check --exclude=xclim/indices/__init__.py xclim
     blackdoc --check docs