		Search-engine friendly clone of the ACL2 documentation.

Git-quick-start

Github-commit-code-using-pull-requests

How to commit code to the books using pull requests

This guide is written for contributors who will probably only commit to the repository a few times a year. If you find yourself committing more often, you should see github-commit-code-using-push.

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 Community ACL2 repository as a git remote:

git remote add upstream https://github.com/acl2/acl2

(B) UPDATING

The following commands will update your local repository to match the latest contents of the ACL2 Community github repository (on the web).

git fetch --all
git merge remotes/upstream/master

(C) CONTRIBUTING

Change and Test

Before beginning your edits, update, as in (B) above:
```
git fetch --all
git merge remotes/upstream/master
```

Build an executable.

(time nice make LISP=<your_lisp>) >& make.log

Make book changes. If you are creating any new books, tell git that you intend to add them (but the local repository on the web won't change until the commit step below is executed).
```
git add file1 file2 ...
```
Also, consider adding some high-level information about your changes to the Community Books' release notes — i.e., the appropriate release-notes-books XDOC topic in books/doc/relnotes.lisp.
Run a regression.
```
(time nice make -j 8 regression-fresh) >& 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 1 above to make appropriate changes and re-test, but you can replace the 'make' step by replacing regression-fresh with regression, since 'make' is clever enough to avoid recertifying more than is necessary. For example:
```
(time nice make -j 8 regression) >& make-regression-finish-1.log
```

Update, and Iterate If Necessary

Update again as in (B) above:

git fetch --all
git merge remotes/upstream/master

The merge may fail if there have been remote updates, that is updates in the repository on the web. In that case, commit your changes locally and then try the merge again. You might want to use the -F option instead of -m; see the next section for more on those options.
git commit -a -m '<some message, with descriptive first line>'
git merge remotes/upstream/master
If the second command (the git merge) prompts you for a message, the empty message should suffice as a reasonable default (in emacs — if vi tries to come up, just type :q and <RETURN>.

You can now go on to the next step (Contribute Your Changes). But ideally: If the output indicates that anything has changed, then go back to ``Change and Test'' above. Of course, you can skip the build if no ACL2 sources have changed, and you can skip making book changes if you are still happy with your changes.

Contribute Your Changes

The following commands will update your github repository on the web. The -m ... option is a log message whose first line should be a summary of your changes and other lines may give more details. You are welcome to replace the -m ... option by -F <filename>, where <filename> is the name of a file that contains your log message.

git commit -a -m '<some message, with descriptive first line>'
git push

You now need to create a pull request, where you request that changes from your github repository be accepted into the Community ACL2 repository. To achieve this:

Goto 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 some explanation about what's in the changes in the comments section. It's helpful if you quote (possibly abbreviated) versions of your commit log messages here, as that way the descriptions are easily read when clicking on the Community Repository commits tab, which goes to https://github.com/acl2/acl2/commits/master.
Click Create pull request.

At this point, the Community ACL2 repository maintainers will be notified, check that things seem to be in order, and then adopt your changes.