Github-commit-code-using-push
How to commit code to the books using direct push access.
This guide is for contributors who commit to the repository
often (e.g., monthly or weekly). Such contributors will typically
begin with the github-commit-code-using-pull-requests method, and
after they are familiar with the process and community, will switch to
this method.
If you do not plan to commit your own changes, see git-quick-start
instead.
(A) GETTING STARTED
Start by obtaining an up-to-date copy of the web-based GitHub
repository (this command makes a directory called acl2 that contains the
current contents of the master branch).
git clone https://github.com/acl2/acl2
cd 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/origin/master
(C) CONTRIBUTING
To join the GitHub project,
please send email to one of the following individuals.
- Eric Smith (eric.smith@kestrel.edu)
- David Rager (ragerdl@gmail.com)
- Sol Swords (sswords@gmail.com)
After you have joined the project, you can proceed as follows when you are
ready to contribute.
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 the main ACL2 repository on GitHub.
git push origin testing
This will cause your changes to be merged into the testing branch.
From there, they will be automatically merged into master if the automated
regression testing system successfully tests them.
Note: If you are changing someone else's files, or would like someone to
review your changes, you might consider making a pull request instead of
pushing directly.
