Github-commit-code-using-pull-requests
How to commit code to the books using pull requests.
This guide is for contributors who will commit to the repository
rarely (e.g., a few times a year). If you find yourself committing more often,
see github-commit-code-using-push.
If you do not plan to commit your own changes, see git-quick-start
instead.
A nice result of using pull requests is that all changes will be peer-reviewed
before being committed. Also, we sometimes call this method the Fork and
Pull method.
(A) GETTING STARTED
- Go to https://github.com/acl2/acl2 and
click on the fork button on the top-right. Fork the repository into
your GitHub space. This will create a new repository at
https://github.com/<your-github-username>/acl2.
- In your working space on your computer, create a clone of your GitHub
repository and cd into it:
git clone https://github.com/<your-github-username>/acl2
cd acl2
- Add the main ACL2 repository as a git remote:
git remote add upstream https://github.com/acl2/acl2
(B) UPDATING
The following commands will update your directory to match the latest
contents of the main ACL2 repository on GitHub.
git fetch --all
git merge -m "Merge." remotes/upstream/master
(C) CONTRIBUTING
Make Changes and Test Them
- Before beginning your edits, update, as in (B) above.
- Build an executable.
make update LISP=<your_lisp>
- Make book changes. See the guidelines in the how-to-contribute topic
(e.g., about updating the book release notes).
- Run a regression.
(make -j 8 regression) >& make-regression.log
Note that the -j 8 option specifies the use of 8 hardware threads; feel
free to omit it or use a more suitable number (especially if your computer has
other than 8 hardware threads).
- Look for failures, as indicated by ** in the log.
fgrep -a '**' make-regression.log
- If there were failures, then go back to Step 3 above to make appropriate
changes and re-test.
- Commit your changes. First do git status to see the list of all
new/changed files:
git status
Ensure that none of the reported additions/changes was unintentional. Next,
do git add to add each file you want to commit (normally, everything
reported by git status, to match what was tested in the regression above):
git add <file1> <file2> ...
Now commit your changes locally:
git commit -m '<some message, with descriptive first line>'
The -m ... option is a log message, where the first line is a summary
of your changes and additional lines give more details. You can replace
the -m ... option by -F <filename>, where <filename> is the
name of a file that contains your log message.
- Merge in remote changes, if any, by updating again as in (B) above.
If the merge changed anything, go back to Step 4 above to ensure that your
changes are compatible with the remote changes you just obtained. If the
merge did not change anything, continue to the next step (Contribute Your
Changes).
In rare cases, you may get a merge conflict (concurrent changes to the same
files), in which case you will need to resolve the conflict by editing files
and committing them (see the git commit command above in Step 7). Then
go back to Step 4 above to test that everything is working.
Contribute Your Changes
The following command will update your fork on GitHub.
git push
You now need to create a
pull request, where you request that changes
from your fork be accepted into the main ACL2 repository.
To achieve this:
- Go to https://github.com/<your-github-username>/acl2.
- Click the New pull request button (you can search for it with your
browser).
- In the drop-down box labeled "base" (next to the box labeled "base
fork"), change the value from "master" to "testing".
- Click Create pull request.
- Put a description of your changes in the comments section.
You may want to quote text from your commit log messages.
- Click Create pull request.
At this point, the main ACL2 repository maintainers will be notified,
check that things seem to be in order, and then either request modifications
or adopt your changes.
