From 5fc914221606fe815f7f03350e492a2afb5349bb Mon Sep 17 00:00:00 2001 From: nstelter-slac Date: Mon, 25 Mar 2024 02:14:44 -0700 Subject: [PATCH] DOC: finish doc pages for workflow, learning git, etc --- README.md | 7 ++-- docs/commands.md | 78 ++++++++++++++++++++++++++++++++++++++ docs/learning_git.md | 17 +++++++++ docs/setup.md | 4 +- docs/standalone_scripts.md | 1 + docs/suite_scripts.md | 3 +- docs/workflow.md | 60 +++++++++++++++++++++++++++++ 7 files changed, 164 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index ed033cc..0501053 100644 --- a/README.md +++ b/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)_  -_(note: in the 1st command: replace \ 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 git@github.com: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 \ No newline at end of file diff --git a/docs/commands.md b/docs/commands.md index e69de29..01f22dd 100644 --- a/docs/commands.md +++ b/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___ +``` + +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 development +``` +* modify and commit the code, which will probably involve usage of the following commands: +``` +git status +git add +git commit -m +``` +* push your feature branch to remote +``` +git push origin +``` +* 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 +``` + +E) Switching between two branches: +* if the following command lists two branches: +``` +git branch +``` +* you can switch between them with: +``` +git checkout +``` + +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 +//ex: 'git checkout v1.0.0' +``` \ No newline at end of file diff --git a/docs/learning_git.md b/docs/learning_git.md index e69de29..29a8bba 100644 --- a/docs/learning_git.md +++ b/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 \ No newline at end of file diff --git a/docs/setup.md b/docs/setup.md index 4bf7367..7c344dd 100644 --- a/docs/setup.md +++ b/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: ``` diff --git a/docs/standalone_scripts.md b/docs/standalone_scripts.md index ac11120..da43f0d 100644 --- a/docs/standalone_scripts.md +++ b/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) diff --git a/docs/suite_scripts.md b/docs/suite_scripts.md index 25223f3..909a3df 100644 --- a/docs/suite_scripts.md +++ b/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) diff --git a/docs/workflow.md b/docs/workflow.md index e69de29..23042fe 100644 --- a/docs/workflow.md +++ b/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\_\\_\\_\_ 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\_\\_\\_\_ 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___ +git push origin beamtime___ +``` + +### During Beamtime: +* At start of beamtime, everyone needs to download the branch for this beamtime: +``` +git fetch +git switch beamtime___ +``` + +* 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 "" +git push origin beamtime___ +``` + +* 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\_\\_\\_\_ +* use a pull request to merge _beamtime\_\\_\\_\_ 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 -a //an example tag number would be 1.0.3 +//this will open your editor to write a description +//the description should be 'Beamtime ' +//(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 \ No newline at end of file