Update a documentation pull request
This topic describes how to respond to test failures and feedback on your pull request.
After you open a pull request, it is tested and reviewed.
After it's approved, the changes are merged into angular/angular
and they become part of the Angular documentation.
While some pull requests are approved with no further action on your part, most pull requests receive feedback that requires you to make a change.
Anatomy of a pull request
After you open a pull request, the pull request page records the activity on the pull request as it is reviewed, updated, and approved. This is an example of the top of a pull request page followed by a description of the information it contains.
Above the pull-request tabs is a summary of the pull request that includes:
-
The pull request title and index
-
The status of the pull request: open or closed
-
A description of the branch with the changes and the branch to update
The tabs contain different aspects of the pull request.
-
Conversation
All comments and changes to the pull request, system messages, and a summary of the automated tests and approvals.
-
Commits
The log of the commits included in this pull request.
-
Checks
The results of the checks run on the commit. This is different from the automated tests that are also run and summarized at the bottom of the Conversation tab.
-
Files changed
The changes this request makes to the code. In this tab is where you find specific comments to the changes in your pull request. You can reply to those comments in this tab, as well.
Respond to a comment
If your pull request receives comments from a reviewer, you can respond in several ways.
-
Reply to the feedback.
For example, you can ask for more information or reply with an explanation.
-
Make the changes to the documentation that the reviewer recommends.
If you update the working branch with the suggested changes, resolve the comment.
-
Make other changes to the documentation.
After reviewing the feedback, you might see an even better improvement. Update the working branch with your improvement and explain why you chose that to your reviewers in a comment.
Remember that pull requests that do not receive a response to a review comment are considered abandoned and closed. For more information about abandoned pull requests, see What happens to abandoned pull requests.
Update a file in the pull request
Follow this procedure to change a file in the pull request or to add a new file to the pull request.
-
In your
git
workspace, in your working directory, checkout your working branch. -
Update the documentation to respond to the feedback you received. The procedures used to revise a documentation topic are also used to update the documentation while there's an open pull request.
-
Test your update locally as described in Testing a documentation update.
-
After your updates have been tested, commit your changes and push the new commits to the working branch of your repo on your
origin
server. -
After you update the working branch on your
origin
server, the fork of theangular/angular
repo in your GitHub account, your pull request updates automatically. -
After the pull request updates, the automated tests are restarted and the reviewers are notified.
Repeat this process as needed to address the feedback you get from reviews of the pull request.
Clean up the branch
If you added commits to address review feedback, you might be requested to clean up your working branch. If some of the commits you made address only review feedback from your reviewers, they can probably be squashed. Squashing commits combines the changes made in multiple commits into a single commit.
To squash commits in your working branch
Perform these steps from a command-line tool on your local computer.
-
In your workspace directory, in your working directory, checkout your working branch.
-
Run this command to view the commits in your working branch.
git log --pretty=format:"%h %as %an %Cblue%s %Cgreen%D"
-
In the output of the previous
git log
command, find the entry that containsupstream/main
. It should be near the top of the list.-
Confirm that entry also contains
origin/main
andmain
If it doesn't, you must resync the clone on your local computer and your
personal/angular
repo with theupstream
repo. After you resync the repos, rebase the working branch before you continue. -
Confirm that all commits for your update are after the entry that contains
upstream/main
Remember that the log output is displayed with the most recent commit first. Your commits should all be on top of the entry that contains
upstream/main
in the log output. If you have commits that are listed after the entry that containsupstream/main
, somehow your commits in the working branch got mixed up. You must fix the branch before you try to squash any commits.
-
-
Count the lines that are on top of the entry that contains
upstream/main
. For example, in this log output, the working branch name isupdate-doc-contribution
and there are five commit entries that are on top of the entry that containsupstream/main
. -
Run this command to squash the commits that occurred after the entry that contains
upstream/main
. In your command, replace the5
afterHEAD
with the number of commits on top of the entry that containsupstream/main
.git rebase -i HEAD~5
-
This command opens your default editor with entries for the commits that you selected in the
git rebase
command. -
To squash the commits, edit the commands in the file that's presented in the editor. The commands in the editor are listed from oldest to newest, which is the opposite order from how they are listed by the
git log
command. The possible command options are listed in the editor below the commands. To squash the commits for your pull request, you only need:pick
andsquash
. -
Review the commands in the editor and change them to match your intention.
The commands are processed from top to bottom, that is from oldest commit to the most recent.\ To merge all commits in this branch for this pull request, change the
pick
commands tosquash
for all commits except for the first one. This text shows how this looks for this example.pick bb0ff71891 docs: update of documentation contrib. guide squash c040d76685 docs: more content for doc updates squash 472585c43f docs: fix links that were broken by renamed files squash 3e6f4c73ac docs: add more info about open PR squash 8e50fad064 docs: more pr docs
With this edit,
git rebase
picks the first commit and combines the later commits into the first one.The commit message of the commit with the
pick
command, is the commit message used for the resulting commit. Make sure that it in the correct format and starts withdocs:
. If you need to change the commit message, you can edit it in the editor. -
After you update the commands, save and exit the editor. The
git rebase
commit processes the commands and updates the commit log in your workspace. In this example, the rebase command combined the five commits to create a single commit in your working branch. This is the commit log after the rebase command completes. -
The
git rebase
command changes the commit log in your local computer so it is now different from the one in your online repo. To update your online repo, you must force your push of changes from your local computer using this command.git push --force-with-lease
This action is also called a force push because it changes the commit log that was stored in your GitHub account. Normally, when you run
git push
, you add new commits to the online repo. When other people have forked a repo, a force push can have undesired effects for them. This force-push is to your forked repo, which should not be shared, so it should be OK. -
After your force push updates the online repo, your pull request restarts the automated tests and notifies the reviewers of the update.
Next steps
Repeat these update steps as necessary to respond to all the feedback you receive.
After you address all the feedback and your pull request has been approved, it is merged into angular/angular
.
The changes in your pull request should appear in the documentation shortly afterwards.
After your pull request is merged into angular/angular
, you can clean up your workspace.