fixed merge

Merge branch 'master' of git.soton.ac.uk:ba1e12/workflow

Conflicts:
	README.md

CONTRIBUTING.md

+Be nice:
+
+ * Please **do not** make changes to the repo master so:
+    * fork the repo
+    * work in a branch of your fork
+    * make a pull request to merge your branch to the master
+ 
+Don't know how to do this? [Read our guide](gitBranches.md).
+ 
+Need more info? Read the excellent [contributing to opensource code](https://opensource.guide/how-to-contribute/) guidance.
\ No newline at end of file

README.md

@@ -4,8 +4,10 @@ How we do collaborative reproducible data analysis and reporting. Mostly (but no
 
 This repo does three things:
 
- * it is a collection of R [how-to resources](resources.md);
+ * it is a collection of R [how-to resources](resources.md) including some notes on:
+   * how to [use git branches](gitBranches.md) 
+   * how to use [drake](https://docs.ropensci.org/drake/) to massively speed up and [manage your workflow](https://milesmcbain.xyz/the-drake-post/)
  * it is a [template](template.md) repo that illustrates how we work and which you can copy;
- * it is an R package that you can build if you want to (not that is has many useful functions).
+ * it is an R package that you can build if you want to using 'install and restart' it from the RStudio Build menu. If you do you will then be able to use its functions viz: `woRkflow::functionName()` (not that it has many).
 
-If you like how we work and want to use the repo as a template for your project or package, just [fork and go](https://happygitwithr.com/fork-and-clone.html).
+If you want to [contribute to the repo](CONTRIBUTING.md) or like how we work and want to use it as a template for your project or package, just [fork and go](https://happygitwithr.com/fork-and-clone.html).
\ No newline at end of file

gitBranches.md

+# git branches - why and how
+
+## why
+
+You will have seen that git/github/gitlab repos have a `master` code base. You should think of this as your 'quality code'. Is is very bad practice to work directly on your master codebase because you could break it (for everyone).
+
+Instead you should work inside a 'branch' of the code and when you have finished the code in the branch you should merge it back in via a pull request. That pull request is an opportunity for you and your team to quality-check or test your work _before_ merging it.
+
+For this reason branches should be small small things that fix or make a specific small contribution rather than a huge mass of changes. Once the work is done, merge the branch and start a new branch for a new task. This stops you trying to fix 2 things in 1 branch and then realising you just want to merge 1 of them in to the master.
+
+## how
+
+We have found the best workflow is to 
+
+ * [fork](https://happygitwithr.com/fork-and-clone.html) the original repo to your personal githib/gitlab account. This means you do not need to be a member of the original repo to work on it. It also helps to prevent accidents to the original master.
+ * create a new RStudio project using _your fork_ of the repo
+   * It's possible you may need to set up a [new ssh key on github](https://happygitwithr.com/ssh-keys.html) to do this. What does this do? It tells github that the device you are using is authenticated. Tip: give the new SSH key on github a helpful name - e.g. the device it is associated with!
+ * add the original master as an [upstream remote](https://happygitwithr.com/upstream-changes.html)
+ * **[create a new branch](https://happygitwithr.com/git-branches.html#create-a-new-branch) in _your fork_ of the orginal repo**. 
+    * Do some work in the new branch
+    * Commit it locally (repeat)
+ * when it works push your new branch back up to the *original* repo
+    * open a new pull request to merge your branch into the master
+    * do your team QA
+    * ask the master code maintainer to accept your pull request
+ * your code is now in the master
+ * delete your branch (to avoid confusion) - this is optional. The point is not to re-use this branch (unless there are errors in it that you need to fix. Your QA should have picked those up!)
+ * pull the changes from the original master to your fork on github
+ * pull these changes to wherever you are working if need be (although the upstream remote described above should avoid this)
+ * **make a new branch for your next task**. etc
+ 
+For this and much more read https://happygitwithr.com/
\ No newline at end of file

resources.md

@@ -9,11 +9,15 @@
     * and much more, although:
         *  we don't agree with [keeping your data in your project](https://rstats.wtf/project-oriented-workflow.html#work-in-a-project). Data should be somewhere else, _unless you're a .gitignore wizard_ and your data is small (and non-sensitive/non-commercial/public etc)
  * using [git(hub/lab)](https://happygitwithr.com/) for version control (perhaps via [usethis](https://usethis.r-lib.org/) and knowing about [ohshitgit](https://ohshitgit.com/) just in case)
- * using [git branches](https://twrushby.wordpress.com/2017/03/27/collaboration-with-rstudio-and-git-using-branches/) as a way for different people to work on the same project without clashing - [ohshitgit](https://ohshitgit.com/) may be required here too
+ * using [git branches](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) as a way for different people to work on the same project without clashing 
+    * Tom has [blogged](https://twrushby.wordpress.com/2017/03/27/collaboration-with-rstudio-and-git-using-branches/) about this
+    * we have written a [short guide](gitBranches.md)
+    * [HappyGit](https://happygitwithr.com/fork-and-clone.html) gives you the details
+    * [ohshitgit](https://ohshitgit.com/) may be required here too (but not if you've followed the instructions above)
  * using [git(hub/lab) issues](https://guides.github.com/features/issues/) as a way to manage your project - just like we did for the [new ECCD website](https://git.soton.ac.uk/SERG/sergwebsite/-/issues)
  * how to use [drake](https://docs.ropensci.org/drake/) to massively speed up and [manage your workflow](https://milesmcbain.xyz/the-drake-post/). This includes always:
     * loading and processing all your data inside a drake plan in a .R file. _So it only gets re-run if the code or data changes_
     * creating each of your output objects inside the drake plan. _So they only get re-created if the code or data changes_
     * rendering your .Rmd report at the end of the drake plan. _So you can pass the params in and report the output objects_
-    * => the first time you run the plan it will build everything. The second time, e.g. after you fix a .Rmd typo, _only the bits that have changed get re-built_.
+    * => the first time you run the plan it will build everything. The second time, e.g. after you fix a .Rmd typo, _only the bits that have changed get re-built_. **Warning: drake can reduce the time it takes to run your code by an order of magnitude. This could seriously damage your tea & cake in-take...**
  
\ No newline at end of file