Merge pull request #2 from shaneknapp/update-contribution-guides

updating contribution documentation

CONTRIBUTING.md

@@ -1,16 +1,16 @@
 # How to contribute and make changes to your user image
 
 ## Setting up your fork and clones
-First, go to your [github profile settings](https://github.com/settings/keys)
+First, go to your [GitHub profile settings](https://github.com/settings/keys)
 and make sure you have an SSH key uploaded.
 
-Next, go to the github repo of the image that you'd like to work on and create
+Next, go to the GitHub repo of the image that you'd like to work on and create
 a fork.  To do this, click on the `fork` button and then `Create fork`.
 
 ![Forking](images/create-fork.png)
 
 
-After you create your fork of the new image repository, you should disable Github Actions **only for your fork**.  To do this, navigate to `Settings` --> `Actions` --> `General` and select `Disable actions`.  Then click `Save`:
+After you create your fork of the new image repository, you should disable GitHub Actions **only for your fork**.  To do this, navigate to `Settings` --> `Actions` --> `General` and select `Disable actions`.  Then click `Save`:
 
 ![Disable fork actions](images/disable-fork-actions.png)
 
@@ -32,13 +32,15 @@ Now `cd` in to `<image-name>` and set up your local repo to point both at the pr
 image repo (`upstream`) and your fork (`origin`).  After the initial clone,
 `origin` will be pointing to the main repo and we'll need to change that.
 
+```
+cd <image-name>
+git remote rename origin upstream # rename origin to upstream
+git remote add origin [email protected]:<your github username>/<image-name>.git # add your fork as origin
+```
+
+To confirm these changes, run `git remote -v` and see if everything is correct:
 ```
 $ cd <image-name>
-$ git remote -v # confirm that origin points to the primary repo
-origin	[email protected]:berkeley-dsep-infra/<image-name>.git (fetch)
-origin	[email protected]:berkeley-dsep-infra/<image-name>.git (push)
-$ git remote rename origin upstream # rename origin to upstream
-$ git remote add origin [email protected]:<your github username>/<image-name>.git # add your fork as origin
 $ git remote -v # confirm the settings
 origin	[email protected]:<your github username>/<image-name>.git (fetch)
 origin	[email protected]:<your github username>/<image-name>.git (push)
@@ -81,7 +83,7 @@ what's been modified and check out the diffs:  `git status` and `git diff`.
 
 ### Building the image locally
 
-You should use [repo2docker](https://repo2docker.readthedocs.io/en/latest/) to build and use/test the image on your own device before you push and create a PR.  It's better (and typically faster) to do this first before using CI/CD.  There's no need to waste Github Action minutes to test build images when you can do this on your own device!
+You should use [repo2docker](https://repo2docker.readthedocs.io/en/latest/) to build and use/test the image on your own device before you push and create a PR.  It's better (and typically faster) to do this first before using CI/CD.  There's no need to waste GitHub Action minutes to test build images when you can do this on your own device!
 
 Run `repo2docker` from inside the cloned image repo.  To run on a linux/WSL2 linux shell:
 ```
@@ -100,11 +102,13 @@ jupyter-repo2docker --user-id=1000 --user-name=jovyan \
 
 If you just want to see if the image builds, but not automatically launch the server, add `--no-run` to the arguments (before the final `.`).
 
+### Pushing the modified files to your fork
+
 When you're ready to push these changes, first you'll need to stage them for a
 commit:
 
 ```
-git add <file1> <file2> <etc>
+git add <file1> <file2> ...
 ```
 
 Commit these changes locally:
@@ -119,6 +123,8 @@ Now push to your fork:
 git push origin <branch name>
 ```
 
+### Creating a pull request
+
 Once you've pushed to your fork, you can go to the image repo and there should
 be a big green button on the top that says `Compare and pull request`.
 Click on that, check out the commits and file diffs, edit the title and
@@ -128,16 +134,18 @@ description if needed and then click `Create pull request`.
 
 ![Create PR](images/create-pr.png)
 
-If you're having issues, you can refer to the [github documentation for pull
+If you're having issues, you can refer to the [GitHub documentation for pull
 requests](https://help.github.com/articles/about-pull-requests/).
 Keep the choice for `base` in the GitHub PR user interface, while the choice
 for `head` is your fork.
 
-Once this is complete and if there are no problems, a github action will
+Once this is complete and if there are no problems, a GitHub action will
 automatically [build and test](https://github.com/berkeley-dsep-infra/hub-user-image-template/blob/main/.github/workflows/build-test-image.yaml)
 the image.  If this fails, please check the output of the workflow in the
 action, and make any changes required to get the build to pass.
 
+### Code reviews and merging the pull request
+
 Once the image build has completed successfully, you can request that
 someone review the PR before merging, or you can merge yourself if you are
 confident. This merge will trigger a [second giuthub workflow](https://github.com/berkeley-dsep-infra/hub-user-image-template/blob/main/.github/workflows/build-push-image-commit.yaml)
@@ -146,5 +154,54 @@ Google Artifact Registry and finally creates and pushes a commit to the
 [Datahub](https://github.com/berkeley-dsep-infra/datahub) repo updating the
 image hash of the deployment to point at the newly built image.
 
+### Creating a pull request in the Datahub repository
+
 You will now need to create a pull request in the Datahub repo to merge these changes
 and deploy them to `staging` for testing.
+
+After the image is built and pushed to the Artifact registry, and the commit
+that modifies that deployment's `hubploy.yaml` is pushed to the Datahub repo,
+there are a couple of different ways you can create the pull request.
+
+#### Via the workflow output
+
+The workflow that builds and pushes has two jobs, and the second job is called
+`update-deployment-image-tag`.  When completed, it will display the output from
+the `git push` command. This contains a clickable link that takes you directly
+to the page to create a pull requests. You can navigate to it by clicking on
+`Actions` in the image repo (not your fork!), and clicking on the latest
+completed job.
+
+![Navigating to the workflow](images/navigate-to-workflow.png)
+
+After you've clicked on the appropriate workflow run, select the
+`udpate-deployment-image-tag` job, and expand 
+`Create feature branch, add, commit and push changes` step.  You will see a
+link there that will direct you to the Datahub repo and create a pull request.
+
+![Create PR from workflow output](images/create-pr-from-workflow.png)
+
+#### Via the Datahub repo
+
+You can also visit the Datahub repo and manually create the pull request there.
+Go to the
+[Pull Request tab](https://github.com/berkeley-dsep-infra/datahub/pulls) and
+click on `New pull request`. You should see a new branch in the list that
+will be from your most recent build. The branch will be named based on
+the image that was updated, and will look something like this:
+
+```
+update-<hubname>-iamge-tag-<new hash of the image>
+```
+
+![Create PR from Datahub repo](images/create-pr-from-datahub-repo.png)
+
+Click on that link, and then on `Create pull request`. 
+
+#### Notify Datahub staff
+Let the Datahub staff know that you've created this pull request and they will review and merge it
+into the `staging` branch. You can notify them via a corresponding GitHub Issue, or on the UCTech
+#datahubs slack channel.
+
+Once it's been merged to `staging`, it will automatically deploy the new image to the hub's
+staging environment in a few minutes and you'll be able to test it out!