updated the documenation to reflect the gitflow workflow and use of d… (

#171)

* updated the documenation to reflect the gitflow workflow and use of develop branch

* removed the redundant text as per review request

* restore text lost in previous commit - unclear review by me

Co-authored-by: balazagi <ssadri@vld711.cmpd1.metoffice.gov.uk>
Co-authored-by: Nick Savage <nhsavage42@gmail.com>

docsrc/instructions.rst

@@ -92,50 +92,39 @@ Create a branch
 ^^^^^^^^^^^^^^^
 
 In Git, creating a branch is a way to start a separate line of development. This is usually done when a developer
-needs to fix a bug or add new features without affecting the current working code.
+needs to fix a bug or add new features without affecting the current working code. The branching method varies depending on the type of workflow  you
+have chosen for CATNIP we are using the Gitflow workflow. More details can be found here:
+https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow
 
-To create a branch off the CATNIP master branch, make sure you are in the checked out directory of your repository,e.g.
-*cd ~/CATNIP* then in case you already have another branch:
+This workflow uses two branches to record the history of the project. A *master* branch to store the stable version of the project
+and a *develop* branch to serve for adding new features. CATNIP already has a develop branch so you only need to check it out, and make your new branch from this (see next section)
 
-First make sure you are in the master branch and run::
-
-    git checkout master
-
-Then create your branch by running this command::
-
-    git branch [branch name]
-
-
-The above command will create the new branch and sets it as your working branch noted by a '*' next to it. You can check this by using this command::
-
-    git branch
-
-output::
-
-      master
-
-    * [branch name]
+Add your feature to the branch
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Before you add a new feature to the project you need to create a *feature_branch* by running the following commands::
 
+    git checkout develop
+    git checkout -b [feature_branch]
 
-Add your function to the branch
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+**Note:** it is a good idea to name your feature branch in a way that is easily identifiable and ideally linked to an already existing
+github issue, e.g. *feature_adding_new_doctest_i123*
 
-Add your function to your branch and develop it. To add your function (from the directory where the working copy of your branch lives)::
+Once you have done your changes to add them to the *feature_branch* make sure you are in the *feature_branch* by running the following commands ::
 
-    git add [file name]
+    git checkout [feature_branch]
+    git add [new/modified file name]
 
-To commit changes to the branch::
+To commit your changes to the *[feature_branch]*::
 
-    git commit -m 'some description for your function'
+    git commit -m 'some description for your changes'
 
 **Note:** More information on git can be found here: https://git-scm.com/doc
 
-
 Pushing your changes to the remote repository
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-you can push your branch to the remote github repository using this command::
+you can push your *[feature_branch]* into the remote *develop* github repository by running this command::
 
-    git push -u origin [branch name]
+    git push -u origin [feature_branch_name]
 
 
 Passing the function to the reviewer
@@ -146,21 +135,27 @@ https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/cr
 
 Check out the branch to be reviewed
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Sometimes to do a review you need to actually work from someone else's branch. To do this we first need to fetch the
-remote branches so that we have access to them locally. Make sure you are in the checked out directory,
+Sometimes to do a review we need to actually work from an already existing branch. To do this we first need to fetch the
+remote branches so that we have access to them locally. Make sure you are in the checked out directory and the *develop* branch,
 e.g. *cd ~/CATNIP*, then run the following command::
 
-    git fetch origin
+    git checkout develop
+    git fetch
 
-Next we check out the branch we want::
+This will list all the branches created off the *develop* branchd. Next we check out the branch we want::
 
-    git checkout -b [remote_branch_name] origin/[remote_branch_name]
+    gti checkout [remote_branch_name]
 
+We can now make our changes and follow the same process as described for the *feature_branch* above.
 
-In later versions of git is simpler::
+Merging into develop/master branch
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Once a pull request for a *feature_branch* is approved the branch can be merged and the local copy deleted. In CATNIP the merging
+into *develop* and *master* branches are done by the admin team. Once a *feature_branch* is merged it can be deleted locally by
+running the following command::
 
-    git fetch
-    gti checkout [remote_branch_name]
+    git checkout develop
+    git branch -d [feature_branch_name]
 
 QA instructions for the reviewer
 ================================