Merge pull request Backblaze#951 from Backblaze/towncrier

Towncrier

.github/workflows/ci.yml

@@ -27,12 +27,11 @@ 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 Command Line Tool
 
-We encourage outside contributors to perform changes to 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 to 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)
   * run 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 supported versions of Python (including PyPy) and 3 operating systems (Linux, Mac OS X, and Windows)
+  * runs all tests on a matrix of supported 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:
@@ -30,6 +66,9 @@ With `nox`, you can run different sessions (default are `lint` and `test`):
 * `test` (`test-3.7`, `test-3.8`, `test-3.9`, `test-3.10`, `test-3.11`) -> Run test suite.
 * `cover` -> Perform coverage analysis.
 * `build` -> Build the distribution.
+* `generate_dockerfile` -> generate dockerfile
+* `docker_test` -> run integration tests against a docker image
+* `build_and_test_docker` -> build a docker image and integration tests against it
 * `deploy` -> Deploy the distribution to the PyPi.
 * `doc` -> Build the documentation.
 * `doc_cover` -> Perform coverage analysis for the documentation.

README.release.md

@@ -1,20 +1,5 @@
 # Release Process
 
-- 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 `nox -s make_release_commit -- X.Y.Z` where `X.Y.Z` is the version you're releasing
 - Copy the main usage string (from `b2 --help`) to `README.md`. Handy command for consistent format: `COLUMNS=4000 b2 --help | awk '/^usages:/ {p=1; next} p {sub(/^ */, "", $0); print}'`
-- Commit and push to a GitHub branch, then wait for CI workflow to complete successfully.
-- Merge the PR
-- Pull from GitHub
-- 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 b2`
-- Update https://www.backblaze.com/b2/docs/quick_command_line.html if needed
+

changelog.d/+fix_docker_run_example.doc.md

@@ -0,0 +1 @@
+Fix `docker run` example in README.md

changelog.d/+towncrier.infrastructure.md

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

noxfile.py

@@ -12,6 +12,7 @@
 import os
 import pathlib
 import platform
+import re
 import string
 import subprocess
 from glob import glob
@@ -45,6 +46,7 @@
 
 REQUIREMENTS_FORMAT = ['yapf==0.27', 'ruff==0.0.272']
 REQUIREMENTS_LINT = REQUIREMENTS_FORMAT + ['pytest==6.2.5', 'liccheck==0.6.2']
+REQUIREMENTS_RELEASE = ['towncrier==23.11.0']
 REQUIREMENTS_TEST = [
     "pexpect==4.8.0",
     "pytest==6.2.5",
@@ -559,3 +561,39 @@ def build_and_test_docker(session):
     generate_dockerfile(session)
     session.run('docker', 'build', '-t', test_image_tag, '.', external=True)
     run_docker_tests(session, test_image_tag)
+
+
+@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

@@ -19,3 +19,46 @@ line-length = 100
 [tool.ruff.per-file-ignores]
 "__init__.py" = ["F401"]
 "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_Command_Line_Tool/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