Merge branch 'doc/instructions' into 'master'

more instructions

See merge request fsl/pytreat-practicals-2020!4

README.md

@@ -65,16 +65,48 @@ https://git.fmrib.ox.ac.uk/fsl/pytreat-practicals-2020
 
 
 Updates to the master branch should occur via merge requests. You can choose
-to either work on a fork of this repository, or on a branch in this
-repository. To contribute to the practicals using a fork:
+to either work on a branch within this repository, or on a fork of this
+repository.
 
+### Using a branch within this repository
+
+1. Make a local clone of the repository:
+
+    ```
+    git clone https://git.fmrib.ox.ac.uk/fsl/pytreat-practicals-2020.git
+    ```
+
+2. Create a branch for your work:
+
+    ```
+    git checkout -b my_cool_branch origin/master
+    ```
+
+3. Make your changes on this branch.
+
+    ```
+    git add <my_new_and_changed_files>
+    git commit -m 'super cool updates'
+    ```
+
+4. Push your changes to the gitlab repository:
+
+    ```
+    git push origin my_cool_branch
+    ```
+
+5. In gitlab, submit a merge request from your branch onto the master
+   branch.
+
+
+### Using a fork of this repository
 
 1. Fork the upstream repository on gitlab
 
 2. Make a local clone of your fork:
 
     ```
-    git clone https://git.fmrib.ox.ac.uk/fsl/pytreat-practicals-2020.git
+    git clone https://git.fmrib.ox.ac.uk/<your_username>/pytreat-practicals-2020.git
     ```
 
 3. Add the upstream repository as a remote:
@@ -85,6 +117,11 @@ repository. To contribute to the practicals using a fork:
 
 4. Make your changes on your local repository
 
+    ```
+    git add <my_new_and_changed_files>
+    git commit -m 'super cool updates'
+    ```
+
 5. Push your changes to your fork:
 
     ```
@@ -95,40 +132,49 @@ repository. To contribute to the practicals using a fork:
    repository.
 
 
-Or, to contribute via a branch:
+### Updating your local repository
 
-1. Make a local clone of the repository:
+To bring in the changes that other people have contributed to the main
+repository into your local repository:
 
-    ```
-    git clone https://git.fmrib.ox.ac.uk/fsl/pytreat-practicals-2020.git
-    ```
 
-2. Create a branch for your work:
+```
+git fetch --all
 
-    ```
-    git checkout -b my_cool_branch origin/master
-    ```
+# make sure you are on the correct local branch - if you followed the
+# instructions above and are working on a fork of the main repository:
+git checkout master
 
-3. Make your changes on this branch.
+# Or if you are working on a branch within the main repository:
+git checkout my_cool_branch
 
-4. Push your changes to the gitlab repository:
+# Do this if you are working on a fork of the main repository
+git merge upstream/master
 
-    ```
-    git push origin my_cool_branch
-    ```
+# Or do this if you are working on a branch within the main repository
+git merge origin/master
+```
+
+
+> Or, if you are comfortable with git, `rebase` is so much cooler:
+>
+> ```
+> git fetch --all
+>
+> # replace <branch_name> with your local branch name
+> git checkout <remote_name>/master
+>
+> # replace <remote_name> with the main repository name
+> git rebase <remote_name>/master
+> ```
 
-5. In gitlab, submit a merge request from your branch onto the master
-   branch.
 
+### Writing your talk as a Jupyter notebook
 
-You may also wish to install
-[`notedown`](https://github.com/aaren/notedown):
+You may wish to install [`notedown`](https://github.com/aaren/notedown):
 
 ```
-source $FSLDIR/fslpython/bin/activate fslpython
-pip install notedown
-source deactivate
-fslpython -m notedown
+$FSLDIR/fslpython/bin/conda install -n fslpython -c conda-forge notedown
 ln -s $FSLDIR/fslpython/envs/fslpython/bin/notedown $FSLDIR/bin/fslnotedown
 ```