diff --git a/_docs/developer/getting_started/commit_to_PR_from_fork.md b/_docs/developer/getting_started/commit_to_PR_from_fork.md new file mode 100644 index 00000000..530f974e --- /dev/null +++ b/_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 git@github.com: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 git@github.com: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 git@github.com:Submitty/Submitty.git (fetch) + origin git@github.com:Submitty/Submitty.git (push) + upstream git@github.com:contributorusername/Submitty.git (fetch) + upstream git@github.com: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). diff --git a/_docs/developer/getting_started/make_a_pull_request.md b/_docs/developer/getting_started/make_a_pull_request.md index de4064a6..10488b01 100644 --- a/_docs/developer/getting_started/make_a_pull_request.md +++ b/_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: diff --git a/_docs/developer/getting_started/review_a_pull_request.md b/_docs/developer/getting_started/review_a_pull_request.md index 1fefb6e0..6085485d 100644 --- a/_docs/developer/getting_started/review_a_pull_request.md +++ b/_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). \ No newline at end of file diff --git a/navtreedata.js b/navtreedata.js index 88d5c479..ffbe8bc4 100644 --- a/navtreedata.js +++ b/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 ]