161 lines
6.8 KiB
Plaintext
161 lines
6.8 KiB
Plaintext
NOTES ON COMMITTING TO EMACS'S REPOSITORY -*- outline -*-
|
|
|
|
* Install changes only on one branch, let them get merged elsewhere if needed.
|
|
|
|
In particular, install bug-fixes only on the release branch (if there
|
|
is one) and let them get synced to the master; do not install them by
|
|
hand on the master as well. E.g. if there is an active "emacs-24" branch
|
|
and you have a bug-fix appropriate for the next emacs-24.x release,
|
|
install it only on the emacs-24 branch, not on the master as well.
|
|
|
|
Installing things manually into more than one branch makes merges more
|
|
difficult.
|
|
|
|
https://lists.gnu.org/r/emacs-devel/2010-03/msg01124.html
|
|
|
|
The exception is, if you know that the change will be difficult to
|
|
merge to the master (eg because the master code has changed a lot).
|
|
In that case, it's helpful if you can apply the change to both master
|
|
and branch yourself (when committing the branch change, indicate
|
|
in the commit log that it should not be merged to the master, by
|
|
including the phrase "Not to be merged to master", or any other phrase
|
|
that matches "merge").
|
|
|
|
* Installing changes from your personal branches.
|
|
|
|
If your branch has only a single commit, or many different real
|
|
commits, it is fine to do a merge. If your branch has only a very
|
|
small number of "real" commits, but several "merge from masters", it is
|
|
preferred that you take your branch's diff, apply it to the master, and
|
|
commit directly, not merge. This keeps the history cleaner.
|
|
|
|
In general, when working on some feature in a separate branch, it is
|
|
preferable not to merge from master until you are done with the
|
|
feature. Unless you really need some change that was done on the
|
|
master while you were developing on the branch, you don't really need
|
|
those merges; just merge once, when you are done with the feature, and
|
|
Git will take care of the rest. Git is much better in this than CVS,
|
|
so interim merges are unnecessary.
|
|
|
|
Or use shelves; or rebase; or do something else. See the thread for
|
|
yet another fun excursion into the exciting world of version control.
|
|
|
|
https://lists.gnu.org/r/emacs-devel/2010-04/msg00086.html
|
|
|
|
* feature and scratch branches
|
|
|
|
Besides the master branch, which is where development takes place, and
|
|
the "emacs-NN" release branches, we also have branches whose names
|
|
start with "scratch/" and "feature/". The "feature/" prefix is used
|
|
for feature branches that are intended to live for some time, while
|
|
"scratch/" is for one-off throw-away-after-use branches.
|
|
|
|
We do not intend to "git merge" from scratch branches, so force-pushes
|
|
are tolerated, as well as commits with poor style, incomplete commit
|
|
messages, etc.
|
|
|
|
We do expect to "git merge" from feature branches so: no force push,
|
|
and no commits that don't have a proper commit message.
|
|
|
|
Automatic tests are run for feature/* branches on EMBA.
|
|
See: https://emba.gnu.org/emacs/emacs/-/pipelines
|
|
|
|
* Installing changes from gnulib
|
|
|
|
Some of the files in Emacs are copied from gnulib. To synchronize
|
|
these files from the version of gnulib that you have checked out into
|
|
a sibling directory of your branch, type "admin/merge-gnulib"; this
|
|
will check out the latest version of gnulib if there is no sibling
|
|
directory already. It is a good idea to run "git status" afterwards,
|
|
so that if a gnulib module added a file, you can record the new file
|
|
using "git add". After synchronizing from gnulib, do a "make" in the
|
|
usual way.
|
|
|
|
To change the set of gnulib modules, change the GNULIB_MODULES
|
|
variable in admin/merge-gnulib before running it.
|
|
|
|
If you remove a gnulib module, or if a gnulib module
|
|
removes a file, then remove the corresponding files by hand.
|
|
|
|
* How to merge changes from emacs-24 to master
|
|
|
|
[The section on git merge procedure has not yet been written.]
|
|
|
|
You may see conflicts in autoload md5sums in comments. Strictly
|
|
speaking, the right thing to do is merge everything else, resolve the
|
|
conflict by choosing either the master or branch version, then run
|
|
'make -C lisp autoloads' to update the md5sums to the correct master
|
|
value before committing.
|
|
|
|
* Re-adding a file that has been removed from the repository
|
|
|
|
Let's suppose you've done:
|
|
|
|
git rm file; git commit -a
|
|
|
|
You can just restore a copy of the file and then re-add it;
|
|
git does not have per-file history so this will not harm
|
|
anything.
|
|
|
|
Alternatively, you can do
|
|
|
|
git revert XXXXX
|
|
|
|
where XXXXX is the hash of the commit in which file was removed.
|
|
This backs out the entire changeset the deletion was part of,
|
|
which is often more appropriate.
|
|
|
|
* Undoing a commit (uncommitting)
|
|
|
|
If you have not pushed the commit, you may be able to use 'git reset
|
|
--hard' with a hash argument to revert the your local repo copy to the
|
|
pre-commit state.
|
|
|
|
If you have pushed commit, resetting will be ineffective because it
|
|
will only vanish the commit in your local copy. Instead, use 'git
|
|
revert', giving it the commit ID as argument. This will create a
|
|
new commit that backs out the change. Then push that.
|
|
|
|
Note that git will generate a log message for the revert that includes
|
|
a git hash. Please edit this to refer to the commit by the first line
|
|
of its log comment, or by committer and date, or by something else
|
|
that is not the hash. As noted previously, it is best to avoid hashes
|
|
in comments in case we someday have to change version-control systems
|
|
again.
|
|
|
|
* Bisecting
|
|
|
|
This is a semi-automated way to find the revision that introduced a bug.
|
|
Browse 'git help bisect' for technical instructions.
|
|
|
|
It is recommended to start a bisection with the admin/git-bisect-start
|
|
script. Using that script ensures that commits in branches that are
|
|
the result of merging external trees into the Emacs repository, as
|
|
well as certain commits on which Emacs fails to build, are skipped
|
|
during the bisection process. That script can also be executed
|
|
automatically when 'git bisect start' is called, with the help of a
|
|
wrapper script that is included in its commentary section.
|
|
|
|
* Maintaining ChangeLog history
|
|
|
|
Older ChangeLog entries are kept in history files named ChangeLog.1,
|
|
ChangeLog.2, etc., and can be edited just as any other source files
|
|
can. Newer ChangeLog entries are stored in the repository as commit
|
|
messages, which cannot be edited directly.
|
|
|
|
'make ChangeLog' copies newer ChangeLog entries into a file
|
|
'ChangeLog' that is intended to be put into the distribution tarball.
|
|
This ChangeLog file is not put into the repository.
|
|
|
|
'make change-history' copies all newer ChangeLog entries into the
|
|
start of the newest ChangeLog history file. These ChangeLog entries
|
|
are thereafter considered to be old, so later uses of 'make ChangeLog'
|
|
and/or 'make change-history' will no longer copy the entries.
|
|
|
|
To alter ChangeLog history, run 'make change-history' and commit the
|
|
changes made by that command. Then edit the ChangeLog history files
|
|
manually and commit those changes in a second, distinct commit.
|
|
Altering ChangeLog history like this can make things harder for those
|
|
who handle merging branches and Emacs releases, so reserve it for
|
|
correcting more serious mistakes.
|