Developers-guide-contributing
Contributing changes
WARNING: This is just a draft. Suggestions for improvements
would be great; please send them to kaufmann@cs.utexas.edu
IMPORTANT: Before reading this topic, be sure to read the topic,
developers-guide-maintenance. The present topic assumes that you have
followed the process there to make changes in your copy of ACL2 and the community-books, including testing and documentation. Here are the steps for
contributing your changes when they are complete and fully tested and
documented.
- Create your modifications by following the processes outlined in the
topic, developers-guide-maintenance. Have you added at least one
release note item? If not, then please look again at the topic, developers-guide-maintenance, where that and other prerequisites are
covered.
- Create a tarball that contains your changes that are NOT under the
books/ directory. For example, if (as is typical) those changes are all
in the top-level ACL2 *.lisp source files, you can do the following while
standing in the ACL2 sources directory:
tar cfz acl2-sources.tgz *.lisp
- Create a git branch on your local machine, called my-branch below
(but give it a more descriptive name, for example, true-list-fix):
git checkout -b my-branch
- Commit your updates that are under books/, but ONLY those
updates. Be sure that the file with your commit message, tmp.msg (or
whatever you decide to call it, but below it is called tmp.msg),
describes your changes to the books. The description can generally be brief
(use git log if you want to see examples), often quoting your new release
note item.
git add books
git commit -F tmp.msg
- Create your own GitHub fork if you don't already have one (for example, as
explained in the documentation topic, github-commit-code-using-pull-requests, Section (A)). Assuming your GitHub
username is my-username and (again) your branch name is my-branch,
this should make your branch publicly accessible at the following URL:
https://github.com/my-username/acl2/tree/my-branch
- Push to your own GitHub fork, as follows:
git push https://github.com/my-username/acl2 my-branch
- Send the commit hash and tarball (see ``Create a tarball'' above), as well
as the name and URL of your new branch (as discussed above), to an ACL2
author. Optionally also send the commit hash for the version of master that
was your starting point. As of this writing, those are to be sent to Matt
Kaufmann, at kaufmann@cs.utexas.edu.
- The last steps will be done by Matt, who will start by getting your
changes as follows, in a fresh directory.
git clone https://github.com/acl2/acl2 .
git fetch https://github.com/my-username/acl2 my-branch:my-branch
git checkout my-branch
Note that after the checkout command just above, my-branch will
contain only your changes. Matt will then install your source code
changes (from the tarball) into the branch, my-branch, possibly make some
edits, and run an `everything' regression. When this passes, Matt will
run the following two commands, where tmp.msg says something about the
changes, with credit to you. Note that the commit command will cause
my-branch to contain all changes, both under books/ and from the
sources tarball, possibly after edits from Matt. NOTE: Matt might instead
decide not to make any edits or run a regression before doing this, in which
case he will do those things after the merge below, as noted below.
git commit -a -F tmp.msg
Finally, Matt will run a merge command so that master contains all
changes (both from books/ and from outside books/), and then
complete the update to master in the GitHub repository.
git checkout master
# Get master up-to-date (this is just ``git pull'' with a check):
bin/pull.sh
git merge my-branch
# Possibly run ``regression-everything'' before the final push just
# below. In fact this is critical if that wasn't done before. There
# may be additional edits and additional commits to master before the
# push just below.
git push https://github.com/acl2/acl2 master
NEXT SECTION: developers-guide-utilities
