diff --git a/RELEASE_PROCEDURE.rst b/RELEASE_PROCEDURE.rst new file mode 100644 index 0000000..3b83005 --- /dev/null +++ b/RELEASE_PROCEDURE.rst @@ -0,0 +1,125 @@ +SAMOS Software Release Procedure +################################ + +In order to keep the repository consistent, and in sync with the software on the WS, this +document describes the release procedures to be used. + +Goals +***** + +These procedures are intended to ensure the following: + +- The github repository matches the code on the WS unless one or the other is actively + being worked on. +- After work is done on either the repository or WS, the two are brought back into + agreement as soon as possible. +- We don't have a bunch of branches around on the repository where it's not clear which + one(s) have work being done, or what work is being done in the branch. +- When looking at a branch, it's clear what the branch is intended to do +- We keep separate changes in separate branches, so that if one is easy and another turns + out to be hard, we can get the easy one merged in while working on the hard one +- We avoid having multiple versions of the SAMOS directory on the WS, without a clear idea + of what their differences are, and why they have those differences. +- Make sure we have 2 pairs of eyes (minimum) on any repository change +- In the SAMOS directory on the WS, we have 3 possible "src" directories: + + - "src" holds the code that will run if you start SAMOS + - "src_testing" holds the current code being tested right now + - "src_working" holds the code that we want to run when doing observations + +Merge Procedure +*************** + +After creating and committing a branch, create a pull request and ask for reviews. If you +receive a request for review, look at the code as soon as possible. Having at least a +second pairs of eyes on the code change is extremely helpful. + +The converse to this is that pull requests should be as small as possible. Especially, +keep files that are not relevant to the changes you made out of the pull request. Any +ephemeral changes (e.g. current DMD position, target planning region files) should not be +added to the repository unless there's a reason that they need to be a part of the code. + +After Making Changes on the WS During Observation +************************************************* + +In this case, it's important to get the repository to reflect the current code running on +the WS. As such, + +1. On the WS, zip the "src" directory inside the SAMOS code. Copy that zip file to your + local machine. Then immediately delete it from the server. +2. If you don't have a clean copy of the repository, clone the SAMOS repository and check + out the "main" branch. +3. Create a new branch in the form "observation__code_updates" using the git command + `git checkout -b BRANCH` +4. Unzip the "src" directory from the WS, and replace the "src" directory in your + repository with this directory. +5. Run `git status` on the repository. If there are any untracked files that need to be + added to the repository, add them. +6. Run `git commit -a -m "MESSAGE"` with MESSAGE describing the changes you made. +7. Run `git push` +8. On the github website, create a pull request from the new branch to main, and request + at least one other SAMOS person to review the pull request. +9. Once the pull request has been approved, merge it in right away, and delete the branch. + +Fixing Bugs or Issues in the Repository +*************************************** + +In this case, we want to make sure the changes are understandable, and we want to make +sure that they are added to the WS before the next observations are taken. + +1. Create a new branch on the repository. For the branch name, *describe the specific + changes that you are making in this branch*. The fewer changes, the better. For + example, if the issue is that the up-arrow button isn't working properly, a branch name + like "fix_up_arrow_button_main_tab" would be good, and any other changes can (and + should) be put in a different branch (using this same procedure for it). +2. Immediately commit and push the changes, and create a pull request to add them to main. +3. Once the PR has been approved, merge it and then delete the branch. +4. make sure that your local repository reflects the changes. +5. Compress the "src" directory from your repository, and copy it to the WS. +6. Replace the "src" directory on the WS with your new copy +7. Delete the zipped src directory. + +Making Upgrades or Enhancements +******************************* + +In this case, the work might take some time to complete, so it's important to make sure +that it stays up-to-date with any other changes that are being made. + +1. Create a new branch describing the upgrade. For example, adding SAMI control to the + GUI might be "upgrade_add_sami_control" +2. Do enough work to make a commit and push the branch to the repository. +3. Create a pull request *and mark it as a draft* +4. Continue work, remembering: + + - If you are making other changes to the repository, remember to update the working + branch so it has those changes added. + - Commit and push your local changes often + - If you need to do work not related to the upgrade, *do it in another branch* as per + one of the other procedures above. + +5. When you have finished the work, test it. If you need to test it on the WS, + + - Compress the "src" directory, and copy it to the WS + - *Rename* the existing WS "src" directory to "src_working" + - Add the testing "src" directory to the SAMOS code on the WS, and delete the + compressed version + - Run your tests + - If there is an existing "src_testing" directory, delete it + - Rename the "src" directory to "src_testing" + - Rename the "src_working" directory to "src" + +6. As soon as the PR is approved, merge it in to main, and delete the branch. +7. Compress the "src" directory from your repository, and copy it to the WS. +8. Replace the "src" directory on the WS with your new copy +9. Delete the zipped src directory. +10. Delete the "src_testing" directory (if present) on the WS + +Github Command Quick Reference +****************************** + +- Create a branch: `git checkout -b ` +- Commit code with message: `git commit -m ""` +- Assign an upstream repository to a branch: `git push --set-upstream origin ` +- Update a branch from the main repo: `git pull origin ` (you must be in your branch + for this to work) +