Merge pull request #573 from nearbeach/documentation

Documentation

docs/005-procedures/deployment/deployment.rst

@@ -13,72 +13,71 @@ Deployment of NearBeach
     `NearBeach on Docker can be found here <https://hub.docker.com/r/robotichead/nearbeach>`_
 
 
-.. note::
-
-    The following instructions will guide you on how to deploy NearBeach to both PyPi and Docker. Please follow the steps
-    in order.
+There are two release processes.
 
+Process 1: should be used when there is new code for NearBeach, and any library updates
 
-.. note::
+Process 2: should be used when there is a security issue within any of the libraries used for NearBeach. This will
+deploy an update for those libraries without sending out any new NearBeach code. aka deploy separately from the
+NearBeach deployment cycle.
 
-    There is a current task opened to automate a lot of this process. These instructions will change in the future so please
-    reference them before each deployment.
+i.e Boto3 has a security patch, and we need to deploy
 
 
 --------------------
-Checklist and Method
+Deployment Process 1
 --------------------
 
-.. note::
-
-    Follow this list in order
-
 
 .. note::
 
-    We are making sure you are in a terminal that is in the root folder of the project
+    Please make sure you are in a terminal, that is in the root folder of the project.
 
-#. Git pull and merge in the main branch. We want any security fixes in node packages
+#. Make sure you are on the develop branch, and all required features have been finished. i.e. merged into the develop
+branch.
 
 #. Run audit tools and fix any packages
 
-#. Remove the `./build` and `./dist` folder
-
-#. Update the version numbers in the following files
+#. Compile the JavaScript into production mode; `npm run prod`
 
-    * `./NearBeach/__init__.py`
+#. Implement the End to End tests using playwright; `npm run e2e`. Please note - you'll need a default instance of
+NearBeach running with the fixture "NearBeach_basic_setup.json".
 
-    * `./package.json`
+#. Check all screenshots from the End to End tests
 
-#. Make sure you are currently using the correct virtual environment; `source ./venv/bin/active`
+#. Make sure the development branch has been pushed into origin. This will include the compilation of the production
+JavaScript
 
-#. Run the unit tests for the django backend to make sure nothing is broken; `python3 ./manage.py test`
+#. Check CircleCI's latest build status for the development branch. All tests should be passing. If there are any tests
+that have failed, they'll need to be fixed before deployment.
 
-#. Run the unit tests for the vue frontend to make sure nothing is broken; `npm run unit`
+#. Using gitflow, we'll create a release. `git flow release start <<version_number>>`. The version number should follow
+the format x.y.z. More information can be found at https://semver.org/
 
-#. Compile the JavaScript into production mode; `npm run prod`
+#. Using gitflow, we'll finish the release. `git flow release finish <<version_number>>`
 
-#. Implement the End to End tests using playwright; `npm run e2e`.
-    Alternatively - if you would like to see UI for the tests use `npm run e2e-ui`
+#. Check the github actions for NearBeach, to see if the workflows are running correctly.
 
-#. Edit the `setup.py` file if there are any new packages that need to be downloaded in the Docker File.
 
-#. Update any virtualenv packages using the following commands
-    `pip list --outdated`
+--------------------
+Deployment Process 1
+--------------------
 
-    `pip install --upgrade <<package_name>>`
+This process should ONLY be followed when we just want to deploy a new version of NearBeach's core libraries without
+deploying any of the new code. i.e. separated from the development cycle.
 
-#. Run the following command to setup the dists file
-    `python3 setup.py sdist bdist_wheel`
+Example 1: Boto3 has a security patch, we need to release this library into NearBeach's docker containers and get
+everyone to use the newest versions.
 
-#. Run the following command to upload NearBeach Application to pypi
-    `python3 -m twine upload dist/* --repository NearBeach`
+#. Go to https://github.com/NearBeach/NearBeach
 
-#. Push the code back upstream, remembering to FORCE PUSH the /NearBeach/static code (as this is  now in gitignore)
+#. On the NearBeach github page, click on the "Create a new release"
 
-#. Do a pull request to merge code back into `main` branch
+#. Appropriately fill out the tag using the version x.y.z - for more information please read https://semver.org/
 
-#. Create a new release off the new `main` branch. This process will trigger the deployment of static files to the CDN
+#. Fill out the rest of the information as approprately as possible. Explain why there is a release, i.e. security patch
+for external library
 
-#. Go the the https://github.com/robotichead/nearbeach-docker and edit the github actions file. Increase the version number. Pushing the code will cause github actions to build the latest docker build and release them.
+#. Make sure the target is "main"
 
+#. Deploy the release

docs/005-procedures/deployment/python-packages.rst

@@ -0,0 +1,11 @@
+.. _python-packages:
+
+=========================
+Upgrading Python Packages
+=========================
+
+The following command lines will help you update your python packages in your virutal environments.
+
+`pip list --outdated`
+
+`pip install --upgrade <<package_name>>`

docs/005-procedures/git-flow/git-flow.rst

@@ -0,0 +1,39 @@
+.. _git-flow:
+
+========
+Git Flow
+========
+
+NearBeach uses Git flow for it's development cycle.
+
+Learning Resources:
+
+* `Github Documentation of Git Flow <https://docs.github.com/en/get-started/using-github/github-flow>`_
+* `Atlassian Documentation of Git Flow <https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow>`_
+* `Git Flow cheat sheet by Daniel Kummer <https://danielkummer.github.io/git-flow-cheatsheet/>`_
+
+Branch Names:
+
++--------------------+--------------------------+
+| Git Default Branch | Branch Name In NearBeach |
++--------------------+--------------------------+
+| Master/Main        | main                     |
++--------------------+--------------------------+
+| Develop            | develop                  |
+|                    |                          |
++--------------------+--------------------------+
+| Feature            | feature                  |
++--------------------+--------------------------+
+| Release            | release                  |
++--------------------+--------------------------+
+| Hotfix             | hotfix                   |
++--------------------+--------------------------+
+
+Notes:
+
+* Any new features, should have the feature created from the `develop` branch
+* Any new hotfixes, should have the hotfix created from the `main` branch
+* Any new releases, will automatically trigger the github actions, and preform a release
+* If releasing new code, the release should be created from the `develop` branch
+* If releasing separate from development, i.e. deploying same code base with updated libraries, then follow the
+  deployment instructions.

docs/005-procedures/index.rst

@@ -7,7 +7,11 @@ Procedures
 The following documents cover procedures around NearBeach.
 
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 1
     :caption: Procedures
 
     Deployment of NearBeach </005-procedures/deployment/deployment>
+
+    Python Packages </005-procedures/deployment/python-packages>
+
+    Git Flow for NearBeach </005-procedures/git-flow/git-flow>