From e84877d4e0ff84eb6840afbbdfc410931a0ea59b Mon Sep 17 00:00:00 2001 From: nstelter-slac Date: Mon, 25 Mar 2024 14:29:23 -0700 Subject: [PATCH] DOC: more updates to doc formating --- README.md | 1 - docs/commands.md | 18 +++++++++--------- docs/environment.md | 4 ++-- docs/index.md | 7 ++++--- docs/learning_git.md | 6 +++--- docs/workflow.md | 8 ++++---- 6 files changed, 22 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 0501053..101dedd 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,6 @@ If everything is working, the script should start spitting terminal-output like: 3260 True Event number foo ``` -_Done with step-by-step setup. The following sections provide more detail on the setup process and the code._ ## Developers: diff --git a/docs/commands.md b/docs/commands.md index 5130dfd..c8f20e7 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -1,18 +1,18 @@ # Git Commands for Common Tasks -**A)** Getting the latest changes for use at a beamtime +### 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 +### B) Getting the latest changes from the _development_ branch ``` git pull origin development ``` -**C)** Saving a new feature/script/bugfix/etc: +### C) Saving a new feature/script/bugfix/etc: * make sure you have the latest changes from the remote: ``` git pull origin development @@ -34,7 +34,7 @@ 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): +### D) If pulling down someone else's branch (non main/development branch): * get updated branch info from remote ``` git fetch origin @@ -48,7 +48,7 @@ git branch -r git checkout ``` -**E)** Switching between two branches: +### E) Switching between two branches: * if the following command lists two branches: ``` git branch @@ -58,18 +58,18 @@ git branch git checkout ``` -**F)** Making pull request (one branch has been pushed to the remote): -* go to: https://github.com/slaclab/beamtime-calibration-suite/pulls +### F) Making pull request (one branch has been pushed to the remote): +* go to: [https://github.com/slaclab/beamtime-calibration-suite/pulls](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 "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): +### G) Check out tagged commit (old beamtime code is tagged): * same syntax as checking-out a branch, but use tag name instead: ``` diff --git a/docs/environment.md b/docs/environment.md index 91b939c..5355c75 100644 --- a/docs/environment.md +++ b/docs/environment.md @@ -5,11 +5,11 @@ When running on S3DF, you will first need to setup your environment so you can r source /sdf/group/lcls/ds/ana/sw/conda2/manage/bin/psconda.sh ``` -Then you can execute the following to setup some project-specific things: +Then you can execute the following to setup some project-specific things (must be ran from _beamtime-calibration-suite_ folder): ``` source setup.sh ``` -_(This must be ran in each new terminal session, or added to your ~/.bashrc file using the full path to setup.sh)_ +_(This must be ran in each new terminal session)_ This script simplifies setting up the terminal environment and will be all that most script users will need to do diff --git a/docs/index.md b/docs/index.md index f0b30d7..1018175 100644 --- a/docs/index.md +++ b/docs/index.md @@ -14,8 +14,9 @@ from calibrationSuite.basicSuiteScript import * from calibrationSuite.fitFunctions import * from calibrationSuite.Stats import * from calibrationSuite.cluster import * +... ``` -_(documentation on the library functionality is still to come, but example usage is seen in the /suite_scripts folder)_ +_(documentation on the library functionality is still to come, but example usage is seen by scripts in the /suite_scripts folder)_ * _/suite_scripts_: scripts that use the calibrationSuite library code ('high-level scripts') * _/standalone_scripts_: scripts that do not use the calibrationSuite library code ('high-level scripts') @@ -25,5 +26,5 @@ _(documentation on the library functionality is still to come, but example usage ### Important branches: -* _development_: Contains the newest 'good' code, usually has new changes and bug fixes. -* _main_: Stable code used during beamtimes. The code from each beamtime (including the changes made during) is tagged. +* _development_: contains the newest 'good' code, usually has new changes and bug fixes. +* _main_: stable code that's used during beamtimes. The code from each beamtime (including the changes made during) is tagged. diff --git a/docs/learning_git.md b/docs/learning_git.md index e903fb8..8584a10 100644 --- a/docs/learning_git.md +++ b/docs/learning_git.md @@ -6,11 +6,11 @@ if you want a good understanding of git, suggest to read the first 3 chapters of * 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) +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) +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) +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) diff --git a/docs/workflow.md b/docs/workflow.md index b2e491d..e8392bd 100644 --- a/docs/workflow.md +++ b/docs/workflow.md @@ -1,12 +1,12 @@ # 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_ +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 +* 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 +* after beamtimes, we merge _beamtime_\_\_\_ back into _main_ and tag it (img: https://www.pablogonzalez.io/salesforce-git-branching-strategies/)