add versioning and updated release docs

Closes #492

docs/developing/github.md

@@ -1,14 +1,15 @@
-# GitHub platform guidelines
+# GitHub Platform Guidelines
 
-This section explains how to interact with GitHub platform for opening Issues and Pull Requests, and some notes how to make a release of the pipeline if you are a mantainer of the code base.
+This section explains how to interact with GitHub platform for opening issues and pull requests (PR), and some notes how to make a release of the pipeline if you are a maintainer of the code base.
+
+The VAST team uses the "git flow" branching model. There are two main branches, `master` and `dev`, both with infinite lifetimes (i.e. they are never deleted). The `master` branch contains stable production-ready code for releases, and `dev` contains the latest reviewed updates for the next release. When `dev` is in a stable state and the software is ready for a new release, the changes are merged into `master` and a new version tag is created to mark it. Development of new features branch off `dev` and merge back into `dev` once completed. Critical bug fixes for released code are done in "hotfix" branches that branch off `master` and merge back into both `master` and `dev` when completed. Finally, "release" branches are made to prepare for a new release and are branched off `dev` and merged into `master` and `dev` when completed. More information on this git flow model can be found [here](https://nvie.com/posts/a-successful-git-branching-model/).
 
 ## Issues Guidelines
 
 * Please search for a similar issue before opening a new one by run a search on the [issue page](https://github.com/askap-vast/vast-pipeline/issues){:target="_blank"} with specific key-words.
 * When opening a new issue, please specify the issue type (e.g. bug, feature, etc.) and provide a detailed description with use cases if applied.
 
-
-## Pull Request Guideline
+## Pull Request Guidelines
 
 ### Opening a PR
 
@@ -21,37 +22,43 @@ This section explains how to interact with GitHub platform for opening Issues an
 
 Steps to issue a pull request:
 
-1. Open an issue (e.g. `My issue blah`, GitHub will assign a id e.g. `#123`).
-2. Branch off `dev` by naming your branch `fix-#123-my-issue-blah` (keep it short please).
-3. Do your changes.
-4. Run test locally with `./manage.py test vast_pipeline` (see the [complete guide on the test](./tests.md) for more details).
-5. Run the webserver and check the functionality.
-6. Commit and issue the PR.
-7. Assign the review to one or more reviewers if none are assigned by default.
+1. Create a new issue on GitHub, giving it a succinct title and describe the problem. GitHub will assign an ID e.g. `#123`.
+2. Create a new branch off the `dev` branch and name the branch based on the issue title, e.g. `fix-123-some-problem` (keep it short please).
+3. Make your changes.
+4. Run the test suite locally with `python manage.py test vast_pipeline`. See the [complete guide on the test](./tests.md) for more details.
+5. Run the webserver and check the functionality. This is important as the test suite does not currently check the web UI.
+6. Commit the changes to your branch, push it to GitHub, and open a PR for the branch.
+7. Update the `CHANGELOG.md` file by adding the link to your PR and briefly describing the changes. An example of the change log format can be found [here](https://github.com/apache/incubator-superset/blob/dev/CHANGELOG.md){:target="_blank"}
+8. Assign the review to one or more reviewers if none are assigned by default.
 
 !!! warning "Warning"
 
     PRs not branched off dev will be __rejected__!.
 
-### Pull Request Review Guidelines
+### Reviewing a PR
+
 The guidelines to dealing with reviews and conversations on GitHub are essentially:
 
 * Be nice :smile: with the review and do not offend the author of the PR: __Nobody is a perfect developer or born so!__
 * The reviewers will in general mark the conversation as "resolved" (e.g. he/she is satisfied with the answer from the PR author).
 * The PR author will re-request the review by clicking on the :octicons-sync-16: on the top right corner and might ping the reviewer on a comment if necessary with `@github_name`.
 * When the PR is approved by at least one reviewer you might want to merge it to dev (you should have that privileges), unless you want to make sure that such PR is reviewed by another reviewer (e.g. you are doing big changes or important changes or you want to make sure that other person is aware/updated about the changes in that PR).
 
-## Releasing Guidelines
-
-In to order to make a release, please follow these steps (example: making the `0.1.0` release):
-
-1. Make sure that every new feature and PR will be merged to dev, before continuing with the releasing process.
-2. Update the [`CHANGELOG.md`](https://github.com/askap-vast/vast-pipeline/blob/master/CHANGELOG.md){:target="_blank"} on `dev` directly (only admin can and need to force-push the changes) with the list of changes. An example of format can be found [here](https://github.com/apache/incubator-superset/blob/dev/CHANGELOG.md){:target="_blank"}.
-3. Update the "announcement bar" in the documentation to refer to the new release. This can be found in `docs/custom_home/main.html` at line 37.
-4. The `0.2.X` branch will be updated by merging `dev` into `0.2.X`.
-5. Branch off `0.2.X` and call it `0.2.1`, then change the `package.json` with the version of the release, commit and tag the commit. Push commit and tag to origin.
-6. Make a release in GitHub using that tag.
-
-__NOTE__: keep the version on `dev` branch to something like 99.99.99dev and in `0.2.X` branch to something like 0.2.99dev. In the release branch, change only the version in [`package.json`](https://github.com/askap-vast/vast-pipeline/blob/master/package.json){:target="_blank"}.
-
-__NOTE__: `dev` branch will be merged to `master` when there is a need to update the production environment.
+## Release Guidelines
+
+In to order to make a release, please follow these steps:
+
+1. Make sure that all new feature and bug fix PRs that should be part of the new release have been merged to `dev`.
+2. Checkout the `dev` branch and update it with `git pull`. Ensure that there are no uncommitted changes.
+3. Create a new branch off `dev`, naming it `release-vX.Y.Z` where `X.Y.Z` is the new version. Typically, patch version increments for bug fixes, minor version increments for new features that do not break backward compatibility with previous versions (i.e. no database schema changes), and major version increments for large changes or for changes that would break backward compatibility.
+4. Bump the version number of the Python package using Poetry, i.e. `poetry version X.Y.Z`. This will update the version number in `pyproject.toml`.
+5. Update the version in `package.json` and `vast_pipeline/_version.py` to match the new version number.
+6. Update the "announcement bar" in the documentation to refer to the new release. This can be found in `docs/theme/main.html` at line 37.
+7. Update the [`CHANGELOG.md`](https://github.com/askap-vast/vast-pipeline/blob/master/CHANGELOG.md){:target="_blank"} by making a copy of the "Unreleased" heading at the top, and renaming the second one to the new version. After this there should be an "Unreleased" heading at the top, immediately followed by another heading with the new version number, which is followed by all the existing changes.
+8. Commit all the changes made above to the new branch and push it to GitHub.
+9. Open a PR to merge the new branch into `master`. Note that the default target branch is `dev` so you will need to change this to `master` when creating the PR.
+10. Once the PR has been reviewed and approved, merge the branch into `master`. This can only be done by administrators of the repository.
+11. Tag the merge commit on `master` with the version, i.e. `git tag vX.Y.Z`. **IMPORTANT:** if you merged the release branch into `master` with the GitHub web UI, you will need to sync that merge to your local copy and checkout `master` before creating the tag. You cannot create tags with the GitHub web UI.
+12. Push the tag to GitHub, i.e. `git push origin vX.Y.Z`.
+13. Merge the release branch into `dev`, resolving any conflicts.
+14. Append "dev" to the version numbers in `pyproject.toml`, `package.json` and `vast_pipeline/_version.py` and commit the change to `dev`.  This can either be done as a new commit, or while resolving merge conflicts in the previous step, if appropriate.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "vast-pipeline",
-  "version": "99.99.99dev",
+  "version": "1.0.0dev",
   "description": "Vast Pipeline code base for processing and analysing telescope images from the Square Kilometre Pathfinder",
   "main": "gulpfile.js",
   "scripts": {

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "vast-pipeline"
-version = "0.2.0"
+version = "1.0.0dev"
 description = "Vast Pipeline code base for processing and analysing telescope images from the Square Kilometre Pathfinder"
 authors = ["The VAST Development Team"]
 license = "MIT"

vast_pipeline/__init__.py

@@ -0,0 +1 @@
+from vast_pipeline._version import __version__  # noqa: F401

vast_pipeline/_version.py

@@ -0,0 +1 @@
+__version__ = '1.0.0dev'