[Documentation:Developer] instructions for pushing to a fork

_docs/developer/getting_started/commit_to_PR_from_fork.md

@@ -0,0 +1,112 @@
+---
+title: How To Checkout and Commit to a PR from a Forked Repository
+category: Developer > Getting Started
+---
+
+Contributors who are part of the Submitty organization on Github can
+make new branches on our Github repositories and should make PRs from
+a *branch directly within the Submitty repository*.  External
+contributors cannot make new branches on the Submitty repositories.
+Instead, external contributors will clone/fork the Submitty repository
+and then make a PR from *a branch on their forked repository*.
+
+It is simpler to review a PR made from a branch, and it is easy to
+make small revisions as needed and commit and push those changes to
+the branch.  It is a little more work to do the same with a PR made
+from a fork, but it is still possible -- *assuming that the owner of
+the forked repository has granted the necessary permissions*.  This
+allows multiple developers to collaborate and finalize a PR for
+merging to the main branch.
+
+The instructions below are for command line use of git.
+
+
+1.  First, from the PR on the Github website, find the name of the
+    fork + branch name.  It should be formatted something like this:
+    ```
+    contributorusername:contributor_branch_name
+    ```
+
+
+2.  Next, make a local branch on your computer in your working repository
+    with the proposed code changes.  Here are the command lines
+    (substitute the fork & branch name we found above):
+
+    If you **are not** using ssh keys on git:
+    ```
+    git checkout -b contributorusername-contributor_branch_name main
+    git pull https://github.com/contributorusername/Submitty.git contributor_branch_name
+    ```
+
+    If you **are** using ssh keys on git:
+    ```
+    git checkout -b contributorusername-contributor_branch_name main
+    git pull [email protected]:contributorusername/Submitty.git contributor_branch_name
+    ```
+
+
+3.  This has made a local branch named
+    `contributorusername-contributor_branch_name`.  Go ahead and test
+    and review the PR and make code edits and new commits to your
+    local branch as needed.
+
+
+
+4.  In order to push the changes to the contributor's fork (and the PR
+    on Github from the fork), you will specify the upstream to be the
+    contributor's fork:
+
+    If you **are not** using ssh keys on git:
+    ```
+    git remote add upstream https://github.com/contributorusername/Submitty.git
+    ```
+
+
+    If you **are** using ssh keys on git:
+    ```
+    git remote add upstream [email protected]:contributorusername/Submitty.git
+    ```
+
+
+    Confirm that the upstream was set:
+    ```
+    git remote -v
+    ```
+
+    Which should print something like this if you **are not** using ssh keys on git:
+    ```
+    origin      https://github.com/Submitty/Submitty.git (fetch)
+    origin      https://github.com/Submitty/Submitty.git (push)
+    upstream    https://github.com/contributorusername/Submitty.git (fetch)
+    upstream    https://github.com/contributorusername/Submitty.git (push)
+    ```
+
+    Or this if you **are** using ssh keys on git:
+    ```
+    origin      [email protected]:Submitty/Submitty.git (fetch)
+    origin      [email protected]:Submitty/Submitty.git (push)
+    upstream    [email protected]:contributorusername/Submitty.git (fetch)
+    upstream    [email protected]:contributorusername/Submitty.git (push)
+    ```
+
+
+5.  Now once you are finished with your code changes, first commit them to
+    the local branch (named
+    `contributorusername-contributor_branch_name`).
+
+    And then push them from your local branch to the external
+    contributor's fork and update the PR on github:
+    ```
+    git push upstream contributorusername-contributor_branch_name:contributor_branch_name
+    ```
+
+    *NOTE:  If you encounter a permissions error, it is possible that the external
+    contributor didn't grant access for collaboration on the branch.*
+
+6.  Confirm that you can see the changes on the Github website for the PR.
+
+
+---
+
+See also [How to Make a Pull Request](make_a_pull_request) and
+[How to Review a Pull Request](review_a_pull_request).

_docs/developer/getting_started/make_a_pull_request.md

@@ -18,7 +18,7 @@ Be sure to read the [Suggestions for New Developers](/developer/getting_started/
 
 
 2. Contributors from outside the Submitty GitHub organization should
-   clone the repo on their own GitHub page, and create a branch with
+   clone/fork the repo on their own GitHub page, and create a branch with
    the modifications to be included with this pull request (PR).
 
    _**IMPORTANT NOTE**:_ Please grant write access to the Submitty
@@ -167,8 +167,11 @@ Be sure to read the [Suggestions for New Developers](/developer/getting_started/
        for specific reviewers.
 
 
+---
+
 See also [How to Review a Pull Request](review_a_pull_request).
 
+---
 
 These guidelines drawn from:
 

_docs/developer/getting_started/review_a_pull_request.md

@@ -53,6 +53,10 @@ What do you need to do?
       Now you have a version of the code in a new branch on the main repo.
       Review the PR normally and delete the temporary branch when you are done
 
+    * If you need to make edits to a PR made from a branch in a forked
+      repo, see:  
+      [How to Checkout and Commit to a Fork PR](commit_to_PR_from_fork)
+
 
 4.  [Re-install the system](/developer/development_instructions/index)
     as necessary
@@ -108,5 +112,6 @@ What do you need to do?
    hopefully, in short order, approving that the code be merged into
    the main branch.
 
+---
 
 See also [How to Make a Pull Request](make_a_pull_request).

navtreedata.js

@@ -187,8 +187,9 @@ var NAVTREE =
             [ "Getting Started", "/developer/getting_started/index", [
                 [ "Overview", "/developer/getting_started/index", null ],
                 [ "Project Ideas", "/developer/getting_started/project_ideas", null ],
-                [ "Review a Pull Request", "/developer/getting_started/review_a_pull_request", null ],
                 [ "Make a Pull Request", "/developer/getting_started/make_a_pull_request", null ],
+                [ "Review a Pull Request", "/developer/getting_started/review_a_pull_request", null ],
+                [ "Commit to PR from Fork", "/developer/getting_started/commit_to_PR_from_fork", null ],
                 [ "Edit Submitty Documentation", "/developer/getting_started/edit_submitty_documentation", null ],
                 [ "VM Install using Vagrant", "/developer/getting_started/vm_install_using_vagrant", [
                     [ "Vagrant QEMU on Apple Silicon", "/developer/getting_started/vm_install_using_vagrant_apple_silicon", null ]