MuseDevelopment

Prerequisites

You will need to install git.

There is a Debian package called git-core that you can install if you use Debian or Ubuntu. If you are using Windows, then visit http://code.google.com/p/msysgit/. Mac OS X users may visit http://code.google.com/p/git-osx-installer/. Otherwise, visit http://git.or.cz and download the latest source.

Shared project repo

If you are a developer that is part of the muse-el project at http://repo.or.cz, you will want to do the following.

git clone ssh://repo.or.cz/srv/git/muse-el.git muse

If you wish to join the Muse development effort, then contact alexott AT gmail.com in order to start the copyright assignment process, and register with http://repo.or.cz (being sure to indicate your ssh public key).

If you do not have developer access but wish to track the latest development changes, do one of the following instead. If you are behind a restrictive firewall, use the second method; otherwise, use the first method.

First:

git clone git://repo.or.cz/muse-el.git muse

Second:

git clone http://repo.or.cz/r/muse-el.git muse

Picking a branch

To see a list of the available branches, run the following command in the checked out copy of Muse.

git branch -r

Here is a description of the available branches.

HEADThe branch you are currently on
masterMain development branch

If you want to browse the available branches via the web, visit http://repo.or.cz/w/muse-el.git.

The default branch that you get when cloning the Muse project is master.

To see which branch you are currently on, do:

git branch

To check out a branch, do the following. This changes the contents of the current directory to match that branch, rather than creating a new directory.

git checkout [branch name]

For the shared branch, this would be the following.

git checkout master

Using the archive

Keeping up-to-date

To keep up-to-date on the latest Muse happenings, run git’s pull command from the directory that contains your copy of Muse.

git pull origin

The name origin refers to the place from which you originally checked out the Muse project.

This will update Muse, taking care to preserve any changes that you have checked in to your local copy.

Telling git your name

If you have made some changes that you would like to commit to the Muse project, first you will need to provide a name and email address. This information is used in the change log for each change you commit. To do this, edit the .gitconfig file in your home directory to include the following contents.

[user]
        name = Your Name Goes Here
        email = you@yourdomain.example.com

Now you are ready to make the change log, and then commit. Read on for the change log instructions before doing the commit.

Committing changes

If you wish to commit just a few files that you have changed, instead of all the files that you have changed, then do the following.

git add changed-file-1
git add changed-file-2
git commit

If you instead wish to commit all changes in one go, then do:

git commit -a

In both cases, git will open an editor that you can use to make a log message. Add a brief one-line description of your changes at the top of the file.

The rest of the file (keeping a blank line after the very first line) is for describing your changes in detail. If you want, you can either leave this blank or just copy the relevant part of your ChangeLog entry here. The information you use here will appear in the muse-el-logs mailing list when you are done.

Make sure that you have described your changes in the ChangeLog file before committing, or at minimum, use ChangeLog-style syntax in your log entries (or something similar to it).

Here is one example of an acceptable commit log.

colors: Fix issue with <lisp> tags too early in #title

* lisp/muse-colors.el: Split the muse-directive-or-comment property into
  two separate properties that are muse-directive and muse-comment.
  (muse-colors-region-end): Make buffer-local.
  (muse-colors-delayed-commands): New variable that contains a list of
  commands to run immediately after highlighting.  This is meant to allow
  highlighting functions to delay code until later.
  (muse-colors-region): Apply commands in muse-colors-delayed-commands.
  (muse-colors-inhibit-tags-in-directives): New variable that determines
  whether tags are allowed in directives.
  (muse-colors-custom-tags): Take muse-colors-inhibit-tags-in-directives
  into account.
  (muse-unhighlight-region): Remove muse-directive and muse-comment
  properties.
  (muse-colors-title): Modify muse-colors-delayed-commands.
  (muse-colors-title-lisp): New command that gets called after
  highlighting other things.  This interprets <lisp> tags, and is
  passed arguments specifying the beginning and end of the region.
  Thanks to <name of contributor> for the report.  The reason we want
  to do things this way is because this is the behavior we get already
  when publishing the page.

* lisp/muse.el (muse-goto-tag-end): Change to use muse-comment property
  rather than muse-directive-or-comment.

Giving changes back

If you have changes that you have committed to Muse, they are only local to your copy of Muse so far. If you want to share them, you must either push them back to the shared repo, or email them to the muse-el-discuss AT gna.org mailing list.

If you have developer access to the shared archive, you can push changes back by doing:

git push origin

If you do not yet have developer access, read on.

You may send your changes via email by doing:

git format-patch -M origin

and then sending the generated patch files to the muse-el-discuss mailing list. Be sure to describe your changes and include a sample ChangeLog entry for them. Be sure that the patch is the body of the message, and not an attachment. Any comments that you wish to make, but don’t want to appear in the commit log, should be placed between the “---” and the diffstat.

If you want to send the resulting patches from the commandline, rather than opening up an email client, you can do the following, where PATCH-FILE is the file that git format-patch made:

git send-email --to muse-el-discuss@gna.org PATCH-FILE

Becoming a Muse Developer

If you want commit access to the shared Muse repository, then register an account at http://repo.or.cz (be sure to add an SSH key), and contact the current maintainer at mwolson AT gnu.org. It would be best to send some patches to the muse-el-discuss AT gna.org mailing list first, so that we know that you know what you are doing.

You must also be willing to sign a copyright assignment for your changes to Muse, since Muse is a GNU project. The current maintainer will assist you in this process if you contact him.

Emacs modes, Tutorials, and Documentation

DVC (see DistributedVersionControl) is a highly-recommended Emacs add-on that allows you to see changes that you have made, log messages, and (eventually) merging changes easily between branches.

Alternatively, the development version of Emacs should include some regular VC bindings for git, so that you can use the same key-bindings that you would use for CVS.

git’s documentation may be browsed at the git website. There has been a significant effort since March 2007 to make the documentation more thorough and easy to read. Several tutorials are there, as well as a User’s Manual.


EmacsMuse