Prepare for release v0.2.0

CHANGELOG.md

@@ -7,8 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [v0.2.0](https://github.com/UCREL/pymusas/releases/tag/v0.2.0) - 2022-01-18
+
 ### Added
 
+- Release process guide adapted from the [AllenNLP release process guide](https://github.com/allenai/allennlp/blob/2cdb8742c8c8c3c38ace4bdfadbdc750a1aa2475/RELEASE_PROCESS.md), many thanks to the AllenNLP team for creating the original guide.
 - A mapping from the [basic CorCenCC POS tagset](https://cytag.corcencc.org/tagset?lang=en) to USAS core POS tagset.
 - The usage documentation, for the "How-to Tag Text", has been updated so that it includes a Welsh example which does not use spaCy instead uses the [CyTag toolkit](https://github.com/UCREL/CyTag).
 - A mapping from the [Penn Chinese Treebank POS tagset](https://verbs.colorado.edu/chinese/posguide.3rd.ch.pdf) to USAS core POS tagset.

CITATION.cff

@@ -23,5 +23,5 @@ authors:
 repository-code: 'https://github.com/ucrel/pymusas'
 url: 'https://ucrel.github.io/pymusas/'
 license: Apache-2.0
-version: 0.1.0
-date-released: '2021-12-07'
+version: 0.2.0
+date-released: '2022-01-18'

README.md

@@ -169,24 +169,6 @@ coverage run -m pytest --doctest-modules pymusas/ # Runs the doc tests
 coverage report # Produces a report on the doc tests coverage
 ```
 
-#### Creating a build and checking it before release
-
-If you would like to build this project and check it with [twine](https://twine.readthedocs.io/en/latest/#twine-check) before release there is a make command that can do this, this command will install `build`, `twine`, and the latest version of `pip`:
-
-``` bash
-make check-twine
-```
-
-#### Validating the CITATION.cff file
-
-If you make any changes to the [CITATION.cff](./CITATION.cff) file, which is the file that contains all of the citation metadata associated with this software package, and you wish to validate your changes against the [citation file format (cff) schema](https://github.com/citation-file-format/citation-file-format/blob/main/schema-guide.md) you can run the following docker command (the docker image is around 257MB in size):
-
-``` bash
-docker run --rm -v $PWD:/app citationcff/cffconvert --validate
-```
-
-For more information about CITATION.cff files see the [Citation File Format website](https://citation-file-format.github.io/).
-
 ## Team
 
 PyMUSAS is an open-source project that has been created and funded by the [University Centre for Computer Corpus Research on Language](https://ucrel.lancs.ac.uk/) (UCREL) at [Lancaster University](https://www.lancaster.ac.uk/). For more information on who has contributed to this code base see the [contributions page.](https://github.com/UCREL/pymusas/graphs/contributors) 

RELEASE_PROCESS.md

@@ -0,0 +1,73 @@
+# PyMUSAS GitHub and PyPI Release Process
+
+**Reference** this guide has been adapted from the [AllenNLP release process guide](https://github.com/allenai/allennlp/blob/2cdb8742c8c8c3c38ace4bdfadbdc750a1aa2475/RELEASE_PROCESS.md), many thanks to the AllenNLP team for creating the original guide.  
+
+This document describes the procedure for releasing new versions of the core library.
+
+> ❗️ This assumes you are using a clone of the main repo with the remote `origin` pointed
+to `[email protected]:UCREL/pymusas.git` (or the `HTTPS` equivalent).
+
+## Steps
+
+1. Set the environment variable `TAG`, which should be of the form `v{VERSION}`.
+
+    For example, if the version of the release is `1.0.0`, you should set `TAG` to `v1.0.0`:
+
+    ```bash
+    export TAG='v1.0.0'
+    ```
+
+    Or if you use `fish`:
+
+    ```fish
+    set -x TAG 'v1.0.0'
+    ```
+
+2. Update `pymusas/__init__.py` with the correct version and check that it matches the `TAG` environment variable you created in the first step.
+
+3. Update the `CHANGELOG.md` so that everything under the "Unreleased" section is now under a section corresponding to this release.
+
+4. Update the `CITATION.cff` file to refer to the right version and date of release. Validate the changes against the [citation file format (cff) schema](https://github.com/citation-file-format/citation-file-format/blob/main/schema-guide.md) you can run the following docker command (the docker image is around 257MB in size):
+
+``` bash
+docker run --rm -v $PWD:/app citationcff/cffconvert --validate
+```
+
+For more information about CITATION.cff files see the [Citation File Format website](https://citation-file-format.github.io/).
+
+5. Check it with [twine](https://twine.readthedocs.io/en/latest/#twine-check). There is a make command that can do this, this command will install `build`, `twine`, and the latest version of `pip`:
+
+    ``` bash
+    make check-twine
+    ```
+
+6. Add these changes using Git manually (`git add`), then commit and push these changes with:
+
+    ```
+    git commit -m "Prepare for release $TAG" && git push
+    ```
+
+7. Then add the tag in git to mark the release:
+
+    ```
+    git tag $TAG -m "Release $TAG" && git push --tags
+    ```
+
+8. Find the tag you just pushed [on GitHub](https://github.com/UCREL/pymusas/tags), click edit, then copy over the output of:
+
+    ```
+    python scripts/release_notes.py
+    ```
+
+9. Click "Publish Release". GitHub Actions will then handle the rest, including publishing the package to PyPI.
+
+
+## Fixing a failed release
+
+If for some reason the GitHub Actions release workflow failed with an error that needs to be fixed, you'll have to delete both the tag and corresponding release from GitHub. After you've pushed a fix, delete the tag from your local clone with
+
+```bash
+git tag -l | xargs git tag -d && git fetch -t
+```
+
+Then repeat the steps above.

makefile

@@ -38,6 +38,7 @@ create-api-docs:
 	@python ./scripts/py2md.py ${DOCS_SRC}
 
 build-python-package:
+	@rm -rf ./dist ./pymusas.egg-info
 	@python -m pip install --upgrade pip
 	@pip install --upgrade build twine
 	@python -m build

scripts/release_notes.py

@@ -0,0 +1,71 @@
+'''
+Reference: This script has been adapted from the AllenNLP repository:
+https://github.com/allenai/allennlp/blob/2cdb8742c8c8c3c38ace4bdfadbdc750a1aa2475/scripts/release_notes.py
+
+Prepares markdown release notes for GitHub releases.
+'''
+
+import os
+from typing import List
+
+import pymusas
+
+
+TAG = os.environ["TAG"]
+
+
+ADDED_HEADER = "### Added 🎉"
+CHANGED_HEADER = "### Changed ⚠️"
+FIXED_HEADER = "### Fixed ✅"
+REMOVED_HEADER = "### Removed 🗑"
+DEPRECATED_HEADER = "### Deprecated 👋"
+SECURITY_HEADER = "### Security 🔒"
+
+
+def get_change_log_notes() -> str:
+    in_current_section = False
+    current_section_notes: List[str] = []
+    with open("CHANGELOG.md") as changelog:
+        for line in changelog:
+            if line.startswith("## "):
+                if line.startswith("## Unreleased"):
+                    continue
+                if line.startswith(f"## [{TAG}]"):
+                    in_current_section = True
+                    continue
+                break
+            if in_current_section:
+                if line.startswith("### Added"):
+                    line = ADDED_HEADER + "\n"
+                elif line.startswith("### Changed"):
+                    line = CHANGED_HEADER + "\n"
+                elif line.startswith("### Fixed"):
+                    line = FIXED_HEADER + "\n"
+                elif line.startswith("### Removed"):
+                    line = REMOVED_HEADER + "\n"
+                elif line.startswith("### Deprecated"):
+                    line = DEPRECATED_HEADER + "\n"
+                elif line.startswith("### Security"):
+                    line = SECURITY_HEADER + "\n"
+                current_section_notes.append(line)
+    assert current_section_notes
+    return "## What's new\n\n" + "".join(current_section_notes).strip() + "\n"
+
+
+def get_commit_history() -> str:
+    stream = os.popen(
+        f"git log $(git describe --always --tags --abbrev=0 {TAG}^^)..{TAG}^ --oneline"
+    )
+    commit_history = "## Commits\n\n" + stream.read()
+    stream.close()
+    return commit_history
+
+
+def main() -> None:
+    assert TAG == f"v{pymusas.__version__}"
+    print(get_change_log_notes())
+    print(get_commit_history())
+
+
+if __name__ == "__main__":
+    main()