Merge branch 'expands-search-api-structure' into add-datagateway-and-…

…panosc-modes-#256

.github/PULL_REQUEST_TEMPLATE.md

@@ -10,6 +10,7 @@ Add a set up instructions describing how the reviewer should test the code
 - [ ] Check GitHub Actions build
 - [ ] If `icatdb Generator Script Consistency Test` CI job fails, is this because of a deliberate change made to the script to change generated data (which isn't actually a problem) or is here an underlying issue with the changes made?
 - [ ] Review changes to test coverage
+- [ ] Does this change mean a new patch, minor or major version should be made? If so, does one of the commit messages feature `fix:`, `feat:` or `BREAKING CHANGE:` so a release is automatically made via GitHub Actions upon merge?
 - [ ] {more steps here}
 
 ## Agile Board Tracking

.github/semantic.yml

@@ -0,0 +1,4 @@
+# Only check commits so we don't need to squash and merge PRs preventing loss of commit history
+commitsOnly: true
+# One or more commits need to follow the Angular commit spec, though ideally we should be using this as much as possible for the changelog
+anyCommit: true

.github/workflows/release-build.yml

@@ -0,0 +1,22 @@
+name: Release Build
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  build:
+    name: Release Build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.ADMIN_PAT }}
+
+      - name: Python Semantic Release
+        uses: relekang/python-semantic-release@master
+        with:
+          github_token: ${{ secrets.ADMIN_PAT }}

CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+<!--next-version-placeholder-->
+
+## v1.0.0 (2021-11-03)
+### Breaking
+* As the API will be approaching production use soon, this seems like a good opportunity to bump the version to 1.0.0. This also serves as a good test that the introduction of automatic versioning actually works  ([`ccf6d29`](https://github.com/ral-facilities/datagateway-api/commit/ccf6d2974216f8979a03e3e223f7c9e84ced05cb))
+
+### Documentation
+* Follow Angular commit message capitalisation #242 ([`d53d85a`](https://github.com/ral-facilities/datagateway-api/commit/d53d85ad46a115ba871c6da8273a242e790c810c))
+* Add documentation to explain versioning on this repo #242 ([`ccf6d29`](https://github.com/ral-facilities/datagateway-api/commit/ccf6d2974216f8979a03e3e223f7c9e84ced05cb))

README.md

@@ -19,6 +19,7 @@ sqlalchemy to communicate directly with ICAT's database.
   - [Automated Testing & Other Development Helpers (Nox)](#automated-testing-&-other-development-helpers-(nox))
   - [Automated Checks during Git Commit (Pre Commit)](#automated-checks-during-git-commit-(pre-commit))
   - [Summary](#summary)
+- [API Versioning](#api-versioning)
 - [Running DataGateway API](#running-datagateway-api)
   - [API Startup](#api-startup)
   - [Authentication](#authentication)
@@ -281,6 +282,59 @@ pre-commit install
 
 
 
+# API Versioning
+This repository uses semantic versioning as the standard for version number
+incrementing, with the version stored in `pyproject.toml`. There is a GitHub Actions
+workflow (`release-build.yml`) which runs when master is updated (i.e. when a pull
+request is merged). This uses
+[python-semantic-release](https://github.com/relekang/python-semantic-release) to
+determine whether a release needs to be made, and if so, whether a major, minor or patch
+version bump should be made. This decision is made based on commit message content.
+
+In a PR, at least one commit must follow the
+[Angular commit message format](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commit-message-format)
+and use one of the
+[conventional commit types](https://github.com/commitizen/conventional-commit-types/blob/master/index.json).
+Note, there are no scopes (part of the Angular message format) configured for this repo
+so there's no need to make use of this feature. Compliance to this format and use of
+standard types will be checked by
+[semantic-pull-requests](https://github.com/zeke/semantic-pull-requests) which is a
+GitHub app installed into this repo and runs alongside existing CI jobs for pull
+requests. For example, the following commit messages follow the conventional commit
+standard:
+
+```
+# Commit to edit a CI job
+ci: edit linting job #issue-number
+
+# Commit for a bug fix
+fix: fix bug found with count endpoints #issue-number
+
+# Commit for a new feature
+feat: add endpoints for search API #issue-number
+
+# Commit which introduces a breaking change for users
+BREAKING CHANGE: change format of `config.json`, the previous version is no longer supported #issue-number
+
+# You can also use `BREAKING CHANGE:` in the additional information if the commit also adds a new feature, like so:
+feat: my new feature #issue-number
+
+BREAKING CHANGE: this feature means X functionality has been removed
+```
+
+For each pull request, only one commit message in this format is required to satisfy the
+semantic pull request checker. Requiring only one commit message in this format should
+hopefully not impose this commit style on developer. However, it is encouraged to use it
+where possible, as the types are also used to form `CHANGELOG.md`.
+
+New releases are only made when a `fix:` (patch), `feat:` (minor) or `BREAKING CHANGE:`
+(major) commit type is found between the previous release and the most recent commit on
+master. When the version is bumped, a GitHub tag and release is made which contains
+the source code and the built versions of the API (sdist and wheel).
+
+
+
+
 # Running DataGateway API
 Depending on the backend you want to use (either `db` or `python_icat`, more details
 about backends [here](#backends)) the connection URL for the backend needs to be set.