Merge pull request #443 from Backblaze/towncrier

Towncrier

.github/workflows/ci.yml

@@ -29,12 +29,9 @@ jobs:
         run: python -m pip install --upgrade nox pip setuptools
       - name: Run linters
         run: nox -vs lint
-      - name: Validate changelog
-        # Library was designed to be used with pull requests only.
-        if: ${{ github.event_name == 'pull_request' && github.actor != 'dependabot[bot]' }}
-        uses: zattoo/changelog@v1
-        with:
-          token: ${{ github.token }}
+      - name: Validate new changelog entries
+        run: if [ -z "$(git diff --diff-filter=A --name-only origin/${{ github.event.pull_request.base.ref }} changelog.d)" ];
+          then echo no changelog item added; exit 1; fi
   build:
     needs: lint
     runs-on: ubuntu-latest

CONTRIBUTING.md

@@ -1,22 +1,58 @@
 # Contributing to B2 Python SDK
 
-We encourage outside contributors to perform changes on our codebase. Many such changes have been merged already. In order to make it easier to contribute, core developers of this project:
+We encourage outside contributors to perform changes on our codebase. Many such changes have been merged already.
+In order to make it easier to contribute, core developers of this project:
 
 * provide guidance (through the issue reporting system)
 * provide tool assisted code review (through the Pull Request system)
 * maintain a set of unit tests
 * maintain a set of integration tests (run with a production cloud)
 * maintain development automation tools using [nox](https://github.com/theacodes/nox) that can easily:
-   * format the code using [yapf](https://github.com/google/yapf)
+   * format the code using [yapf](https://github.com/google/yapf) and [ruff](https://github.com/astral-sh/ruff)
    * runs linters to find subtle/potential issues with maintainability
    * run the test suite on multiple Python versions using [pytest](https://github.com/pytest-dev/pytest)
 * maintain Continuous Integration (by using GitHub Actions) that:
    * runs all sorts of linters
    * checks if the Python distribution can be built
-   * runs all tests on a matrix of 6 versions of Python (including pypy) and 3 operating systems (Linux, Mac OS X and Windows)
+   * runs all tests on a matrix of 6 versions of Python (including pypy) and 3 operating systems 
+     (Linux, Mac OS X and Windows)
    * checks if the documentation can be built properly
 * maintain other Continuous Integration tools (coverage tracker)
 
+## Versioning
+
+This package's versions adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and the versions are
+established by reading git tags, i.e. no code or manifest file changes are required when working on PRs.
+
+## Changelog
+
+Each PR needs to have at least one changelog (aka news) item added. This is done by creating files in `changelog.d`.
+`towncrier` is used for compiling these files into [CHANGELOG.md](CHANGELOG.md). There are several types of changes 
+(news):
+
+1. fixed
+2. changed
+3. added
+4. deprecated
+5. removed
+6. infrastructure
+7. doc
+
+
+The `changelog.d` file name convention is:
+
+1. If the PR closes a github issue: `{issue_number}.{type}.md` e.g. `157.fixed.md`. Note that the
+   change description still has to be complete, linking an issue is just there for convenience, a change like 
+   `fixed #157` will not be accepted.
+2. If the PR is not related to a github issue: `+{unique_string}.{type}.md` e.g. `+foobar.fixed.md`. 
+
+These files can either be created manually, or using `towncrier` e.g.
+
+    towncrier create -c 'write your description here' 157.fixed.md
+
+`towncrier create` also takes care of duplicates automatically (if there is more than 1 news fragment of one type 
+for a given github issue).
+
 ## Developer Info
 
 You'll need to have [nox](https://github.com/theacodes/nox) installed:

README.release.md

@@ -1,25 +1,3 @@
 # Release Process
 
-- Get the Nox:
-  - `pip install -U nox`
-- Update the release history in `CHANGELOG.md`:
-  - Change "Unreleased" to the current release version and date.
-  - Create empty "Unreleased" section.
-  - Add proper link to the new release (at the bottom of the file). Use GitHub [compare feature](https://docs.github.com/en/free-pro-team@latest/github/committing-changes-to-your-project/comparing-commits#comparing-tags) between two tags.
-  - Update "Unreleased" link (at the bottom of the file).
-- Run linters and tests:
-  - `export B2_TEST_APPLICATION_KEY=your_app_key`
-  - `export B2_TEST_APPLICATION_KEY_ID=your_app_key_id`
-  - `nox -x`
-- Build docs locally:
-  - `nox --non-interactive -xs doc`
-- Commit and push to GitHub, then wait for CI workflow to complete successfully.
-  - No need to make a branch. Push straight to `master`.
-- Tag in git and push tag to origin.  (Version tags look like "v0.4.6".)
-  - `git tag vx.x.x`
-  - `git push origin vx.x.x`
-- Wait for CD workflow to complete successfully.
-  - Verify that the GitHub release is created
-  - Verify that the release has been uploaded to the PyPI
-- Install using pip and verify that it gets the correct version:
-  - `pip install -U b2sdk`
+- Run `nox -s make_release_commit -- X.Y.Z` where `X.Y.Z` is the version you're releasing, and follow the instructions

changelog.d/+towncrier.infrastructure.md

@@ -0,0 +1 @@
+Towncrier changelog generation - to avoid conflicts when simultaneously working on PRs

noxfile.py

@@ -10,6 +10,8 @@
 from __future__ import annotations
 
 import os
+import re
+import subprocess
 
 import nox
 
@@ -32,6 +34,7 @@
 
 REQUIREMENTS_FORMAT = ['yapf==0.27', 'ruff==0.0.270']
 REQUIREMENTS_LINT = REQUIREMENTS_FORMAT + ['pytest==6.2.5', 'liccheck==0.6.2']
+REQUIREMENTS_RELEASE = ['towncrier==23.11.0']
 REQUIREMENTS_TEST = [
     "pytest==6.2.5",
     "pytest-cov==3.0.0",
@@ -206,3 +209,39 @@ def doc_cover(session):
         # If there is no undocumented files, the report should have only 2 lines (header)
         if sum(1 for _ in fd) != 2:
             session.error('sphinx coverage has failed')
+
+
+@nox.session(python=PYTHON_DEFAULT_VERSION)
+def make_release_commit(session):
+    """
+    Runs `towncrier build`, commits changes, tags, all that is left to do is pushing
+    """
+    if session.posargs:
+        version = session.posargs[0]
+    else:
+        session.error('Provide -- {release_version} (X.Y.Z - without leading "v")')
+
+    if not re.match(r'^\d+\.\d+\.\d+$', version):
+        session.error(
+            f'Provided version="{version}". Version must be of the form X.Y.Z where '
+            f'X, Y and Z are integers'
+        )
+
+    local_changes = subprocess.check_output(['git', 'diff', '--stat'])
+    if local_changes:
+        session.error('Uncommitted changes detected')
+
+    current_branch = subprocess.check_output(['git', 'rev-parse', '--abbrev-ref', 'HEAD']).decode()
+    if current_branch != 'master':
+        session.log('WARNING: releasing from a branch different than master')
+
+    session.run('pip', 'install', *REQUIREMENTS_RELEASE)
+    session.run('towncrier', 'build', '--yes', '--version', version)
+
+    session.log(
+        f'CHANGELOG updated, changes ready to commit and push\n'
+        f'    git commit -m release {version}\n'
+        f'    git tag v{version}\n'
+        f'    git push {{UPSTREAM_NAME}} v{version}\n'
+        f'    git push {{UPSTREAM_NAME}} {current_branch}'
+    )

pyproject.toml

@@ -15,3 +15,46 @@ target-version = "py37"
 "b2sdk/v*/**" = ["I", "F403", "F405"]
 "b2sdk/_v*/**" = ["I", "F403", "F405"]
 "test/**" = ["D", "F403", "F405"]
+
+[tool.towncrier]
+directory = "changelog.d"
+filename = "CHANGELOG.md"
+start_string = "<!-- towncrier release notes start -->\n"
+underlines = ["", "", ""]
+title_format = "## {version} - {project_date}"
+issue_format = "[#{issue}](https://github.com/Backblaze/b2-sdk-python/issues/{issue})"
+
+[[tool.towncrier.type]]
+directory = "removed"
+name = "Removed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "changed"
+name = "Changed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "fixed"
+name = "Fixed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "deprecated"
+name = "Deprecated"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "added"
+name = "Added"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "doc"
+name = "Doc"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "infrastructure"
+name = "Infrastructure"
+showcontent = true