Merge pull request #65 from slaclab/more_docs_3

DOC: finish doc pages for workflow, learning git, etc

README.md

@@ -4,7 +4,7 @@
 # Docs: https://slaclab.github.io/beamtime-calibration-suite/
 
 # Step-by-step to get running quick!
-* First, follow steps **1** through **4**: [setup git and github](https://slaclab.github.io/beamtime-calibration-suite/setup/)
+* First, follow steps **1** through **7**: [Github and Git Setup](https://slaclab.github.io/beamtime-calibration-suite/setup/)
 * Next, run the following commands in a terminal (linux or mac terminal should work):  
  -_(note: lines starting with '#' are comments with explanation and don't need to be ran)_  
 &emsp;-_(note: in the 1st command: replace \<slac-username> with your slac linux-username)_
@@ -20,6 +20,7 @@ source /sdf/group/lcls/ds/ana/sw/conda2/manage/bin/psconda.sh
 mkdir repos && cd repos
 git clone [email protected]:slaclab/beamtime-calibration-suite.git
 cd beamtime-calibration-suite
+git fetch
 git switch development
 
 # do more environment setup for suite-scripts
@@ -42,8 +43,8 @@ _Done with step-by-step setup. The following sections provide more detail on the
 
 ## Developers:
 
-If you are new to git/github, start here: [https://confluence.slac.stanford.edu/pages/viewpage.action?pageId=428802060](https://confluence.slac.stanford.edu/pages/viewpage.action?pageId=428802060)
+If you are new to git/github, start [here](https://slaclab.github.io/beamtime-calibration-suite/learning_git/)
 
-Then read the following for an overview of the development process: [https://confluence.slac.stanford.edu/pages/viewpage.action?pageId=429562464](https://confluence.slac.stanford.edu/pages/viewpage.action?pageId=429562464)
+An overview of the development process is found [here](https://slaclab.github.io/beamtime-calibration-suite/workflow/)
 
 For commit messages, we can try to follow the PyDM guidelines: https://slaclab.github.io/pydm/development/development.html#commit-guidelines

docs/commands.md

@@ -0,0 +1,78 @@
+# Git Commands for Common Tasks
+
+A) Getting the latest changes for use at a beamtime
+```
+git fetch
+//if beamtime is across multiple days, use 1st day date
+git switch beamtime_<month>_<day>_<year>
+```
+
+B) Getting the latest changes from the _development_ branch
+```
+git pull origin development
+```
+
+C) Saving a new feature/script/bugfix/etc:
+* make sure you have the latest changes from the remote:
+```
+git pull origin development
+```
+* make a branch for your feature off of the _development_ branch:
+```
+git checkout -b <feature_branch_name> development
+```
+* modify and commit the code, which will probably involve usage of the following commands:
+```
+git status
+git add <filename>
+git commit -m <commit-message>
+```
+* push your feature branch to remote
+```
+git push origin <feature_branch_name>
+```
+* if want to merge your changes into the _development_ branch (and keep them long-term)
+  * follow **F)** and make a pull-request from your feature-branch into _development_
+
+D) If pulling down someone else's branch (non main/development branch):
+* get updated branch info from remote
+```
+git fetch origin
+```
+* see list of remote branches (optional)
+```
+git branch -r
+```
+* checkout their branch (use the branch name without the 'oriogin/' prefix)
+```
+git checkout <other_person_branch_name>
+```
+
+E) Switching between two branches:
+* if the following command lists two branches:
+```
+git branch
+```
+* you can switch between them with:
+```
+git checkout <branch_want_to_switch_to>
+```
+
+F) Making pull request (one branch has been pushed to the remote):
+* go to: https://github.com/slaclab/beamtime-calibration-suite/pulls
+* click green 'New pull request' button in upper right
+* you will see two grey boxes containing branch names and an arrow pointing from one box to the other
+  * the "compare:..." box is the branch that will get merged into the "base:..." box's branch
+  * the base should be the branch named _development_
+* once the grey boxes are set correctly, click the green 'Create pull request' button
+* once branch is ready to merge, you can click the ''Merge pull request' button to merge the commit
+  * being ready means: potentially reviewed (if big change), passing any automated checks/tests, etc
+* if github is not allowing the merge automatically, you will need to merge or rebase locally and manually handle the conflicts
+
+G) Check out tagged commit (old beamtime code is tagged):
+
+* same syntax as checking-out a branch, but use tag name instead:
+```
+git checkout <tag_name>
+//ex: 'git checkout v1.0.0'
+```

docs/learning_git.md

@@ -0,0 +1,17 @@
+# Learning Git
+
+* this project uses _git_ as a version control system, along with the [GitHub](https://github.com/) website for hosting the code and multiple other features.
+
+* if you want a good understanding of git, suggest to read the first 3 chapters of [https://git-scm.com/book/en/v2](https://git-scm.com/book/en/v2):
+  * the following sections could be skipped: _1.5, 1.6, 2.6, 2.7, 3.5, 3.6_
+  * the book is a recommended resource by the git community but many other tutorials exist, so feel free to use other 'intro to git/github' videos/websites
+
+* a short presentation that summaries the book's content can be found [here](https://courses.cs.washington.edu/courses/cse403/13au/lectures/git.ppt.pdf)  
+
+* a presentation by SLAC that explains git, github, git workflow, etc can be found [here](https://docs.google.com/presentation/d/1AXcH17xDfum4mZsdV5lfjn_mvSMp2ye796xrVuSM3w8/edit#slide=id.gf4dca9affc_0_7)
+
+* a git commands cheat-sheet can be found here [here](https://www.jrebel.com/system/files/git-cheat-sheet.pdf) (**link will start download of pdf cheat sheet)  
+
+* (if you plan on developing the library) read about GitHub's 'Pull Request' feature here [here](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests)
+
+* for commit messages, we can try to follow the PyDM guidelines: https://slaclab.github.io/pydm/development/development.html#commit-guidelines

docs/setup.md

@@ -58,7 +58,7 @@ git config --global core.editor emacs
 * Follow instructions under “Adding a new SSH key to your account”: [https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account#adding-a-new-ssh-key-to-your-account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account#adding-a-new-ssh-key-to-your-account)
 
 
-## 5: Download the repo
+## 7: Download the repo
 
 * run the following terminal commands:
 ```
@@ -78,7 +78,7 @@ ls
 * if an error occurs during these commands, SSH setup in step **6)** may have had an issue and might need to be debugged
 
 
-## 6: Run an example script
+## 8: Run an example script
 
 * run the following terminal commands:
 ```

docs/standalone_scripts.md

@@ -1,4 +1,5 @@
 # Standalone scripts:
+wip: add descriptions, how to run, etc
 * [cfg_utils.py](https://github.com/slaclab/beamtime-calibration-suite/blob/development/standalone_scripts/cfg_utils.py)
 * [dumpPVs.py](https://github.com/slaclab/beamtime-calibration-suite/blob/development/standalone_scripts/dumpPVs.py)
 * [plotWave8.py](https://github.com/slaclab/beamtime-calibration-suite/blob/development/standalone_scripts/plotWave8.py)

docs/suite_scripts.md

@@ -1,4 +1,5 @@
-# Suite scripts:
+# Suite scripts: 
+wip: add descriptions, how to run, etc
 * [AnalyzeH5.py](https://github.com/slaclab/beamtime-calibration-suite/blob/development/suite_scripts/AnalyzeH5.py)
 * [runAnalyzeH5.py](https://github.com/slaclab/beamtime-calibration-suite/blob/development/suite_scripts/runAnalyzeH5.py)
 * [runInfo.py](https://github.com/slaclab/beamtime-calibration-suite/blob/development/suite_scripts/runInfo.py)

docs/workflow.md

@@ -0,0 +1,60 @@
+# Git/GitHub Workflow
+
+We should try to generally follow the branching and pull-request workflow described in this [presentation](https://docs.google.com/presentation/d/1AXcH17xDfum4mZsdV5lfjn_mvSMp2ye796xrVuSM3w8/edit#slide=id.gf4dca9affc_0_7).
+* in our case the two important branches will be _main_ and _development_
+* in-between beamtimes, _development_ is used for pushing work 
+* right before beamtimes, _development_ is merged into _main_ 
+* then a branch named _beamtime\_\<month\>\_\<day\>\_\<year\>_ is branched off main
+  * this branch is used for sharing code fixes/changes (pushing-to and pulling-from) during beamtime
+* after beamtimes, we merge _beamtime\_\<month\>\_\<day\>\_\<year\>_ back into _main_ and tag it
+
+(img: https://www.pablogonzalez.io/salesforce-git-branching-strategies/)
+
+### Before Beamtime:
+* checkout _development_ (or a earlier stable point of _development_) 
+* manually run and check the output of script planned for use on the beamtime, as a final sanity check
+* use a pull request to merge _development_  into _main_
+  * to do this follow the instructions in section **F)** of [https://slaclab.github.io/beamtime-calibration-suite/commands/](https://slaclab.github.io/beamtime-calibration-suite/commands/)
+  * _main_ is safeguarded and will require a +1 from another developer
+* make a branch for work during this specific beamtime
+```
+git checkout -b main beamtime_<month>_<day>_<year>
+git push origin beamtime_<month>_<day>_<year>
+```
+
+### During Beamtime:
+* At start of beamtime, everyone needs to download the branch for this beamtime:
+```
+git fetch
+git switch beamtime_<month>_<day>_<year>
+```
+
+* If you need to make changes to the code, first make sure your files are up to date:
+```
+git pull
+```
+* Now make your changes and upload them:
+```
+git add -u
+git commit -m "<description of changes made>"
+git push origin beamtime_<month>_<day>_<year>
+```
+
+* If someone else made and upload changes, you can download them by doing:
+```
+git pull
+```
+
+### After Beamtime:
+* make sure all the changes that need to be saved are commited to _beamtime\_\<month\>\_\<day\>\_\<year\>_ 
+* use a pull request to merge _beamtime\_\<month\>\_\<day\>\_\<year\>_  into _main_
+* add a tag for the beamtime
+```
+//tag number is arbitrary at this point, just look at last tag and increment one of the values
+git tag v<tag number> -a //an example tag number would be 1.0.3
+//this will open your editor to write a description
+//the description should be 'Beamtime <Month> <Day> <Year>'
+//(if beamtime is multiple days, use the 1st day's date)
+```
+* use a pull request to merge _main_ into _development_
+  * this is kinda sloppy, but seems like easiest way to 'reset' things after beamtime