This is the First edition of the SXEmacs Policies & Procedures Manual

This is the SXEmacs Policies & Procedures Manual. It was last updated June 13, 2015.

Copyright © 2004 - 2015 Steve Youngs.

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public Licence, Version 2.

     Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.

This document, as its name implies, is directed towards anyone who is actively involved (or thinking of becoming actively involved) in the development of SXEmacs (http://www.sxemacs.org/).

SXEmacs Mission Statement
*************************

Our mission is to...

     To provide the Open Source community with a text editing and development environment that is based on XEmacs and is 2nd to none in regards to stability, features, and innovation.

     To foster a user and developer friendly project environment.

     And, above all, to have fun doing it.

SXEmacs' Online Presence
************************

The SXEmacs project maintains a number of online services. Including...

  * The SXEmacs Web Site (http://www.sxemacs.org/)

  * Release and Snapshot Tarballs (http://downloads.sxemacs.org/)

  * The SXEmacs IRC channel (irc://irc.freenode.net/#sxemacs)

  * The SXEmacs Issue Tracker (http://issues.sxemacs.org/) Bug Reports Feature Requests Support Requests.

  * SXEmacs Merchandise (http://store.sxemacs.org/)

SXEmacs Web Site
****************

The SXEmacs web site content is kept under the same version control system as SXEmacs itself Version Control.  That means that anyone can submit changes and updates to the site in the same manner that they would for code submissions to SXEmacs see Patches.

There's really not much more to tell about the web site.  It is just your normal run-of-the-mill web site.  And as everyone knows, HTML blows goats so it doesn't get updated anywhere near as often as it should.  We do have a Webmaster, so if you do have any comments about the site, you should direct them there. Or, alternatively, SXEmacs Devel mailing list.

SXEmacs Download Site
*********************

SXEmacs release downloads (http://downloads.sxemacs.org/releases/) is where you'll find release tarballs and release to release patches available for download.

SXEmacs snapshot downloads (http://downloads.sxemacs.org/snapshots/) is where you can find snapshot tarballs which are uploaded from time to time.  Please note that these snapshots can sometimes be very unstable.

If you would like something made available for download at the SXEmacs download site, contact Steve Youngs.

SXEmacs on IRC
**************

Developers official communcation platform is the mailing list provided at sxemacs.org. However, to discuss problems and assist users more efficiently there is an official IRC channel.

SXEmacs IRC channel #sxemacs is located at freenode (formerly known as OPN). Please use following URI to refer to it:

irc://irc.freenode.net/#sxemacs

Various IRC HowTOs
------------------

  * Connecting to the network and joining the channel

     Fire up your favourite irc client and use: /server irc.freenode.net to connect to the network and /join #sxemacs to join the community.

  * HowTo become a respected regular

     Okay, you've decided to be active on IRC and hopefully help other users. You have joined the channel and idle around thirsting for hard problems by helpless users.

     In that case you will have to have a reliable (not-changing) nickname that is linked to your person in order to refer to you.  This will help us in blaming you if you misdirect users with your answers and even help us to praise you if you convinced RMS to switch to SXEmacs ;)

     Therefore, freenode provides a mechanism to eternalise yourself via the nickname you carry. Use /nickserv register <password> to engrave your nickname for your personal use.

     This nickname is yours from now on. To identify yourself to freenode use /nickserv identify <samepasswordasabove>

     Your user mode will be changed to +e in case of successful identification.

     Whenever you see unscrupulous people carrying your nickname or your nickname is ghosted because of a reconnection, you can just /nickserv ghost <yournickname> <yourpassword> to send the other client to oblivion.

     Okay, now that you've registered yourself with freenode, you're nickname can be referred to, independently from whether you are carrying that nick or not. Just do /nickserv info <nickname> to obtain some information on a nickname you see and like to refer to.

  * HowTo to be listed in the channel access list

     There is no influence on this access list on the users and developer's side.  It is merely up to the project lead who has control over it.

  * Host cloaks

     The only way to get one is to ask the project lead (SteveYoungs).

  * No IRC client

     You don't have an IRC client but still want to shoot the breeze with us on IRC?  Then we have an answer for you... Chat from the web (http://www.sxemacs.org/irc.html).

SXEmacs Merchandise
*******************

At The SXEmacs Store (http://store.sxemacs.org/) you will find for sale various cool and sexy goodies sporting the SXEmacs logo.  The proceeds from all purchases go toward covering the costs involved in the upkeep of the SXEmacs project.  Be the first on your street to own a I'm Too Sexy For My Emacs T-shirt!

Dispute Resolution
******************

     When two people agree on everything, one of them isn't needed.

I can't remember where that quote comes from so if anyone reading this knows, please let us know so we can give credit where credit is due.

We are all mature adults and most of the time we don't let our egos get in the way of getting things done.  But human nature being what it is means that from time to time we'll have conflict or disagreements.  In the vast majority of these cases a resolution will come quickly and easily through reasonable discussion.

This section is for those rare occasions that will be the exception to the above.

In the event of a unresolvable dispute, the SXEmacs Project Lead, Steve Youngs, will, at his discretion, take one or more of the following steps...

  * Decide the outcome.

  * Call a vote Voting.

  * Call a postponement.  This will mean that all parties will be asked to stop discussing the matter until some date in the future.  This future date will be given at the time the SXEmacs Project Lead calls the postponement.  The idea here is to give everyone a chance to cool down so that reasonable discussion can continue.

To date, we've not ever had to resort to these.  We tend to sort things out pretty quickly and amicably most of the time.

Voting
******

Sometimes things are best decided with a vote.  This section describes how these votes are to be held.

Who may participate in a vote?  Anyone subscribed to the SXEmacs Developers' mailing list, sxemacs-devel@sxemacs.org.

Who may call a vote?  The SXEmacs Project Lead, Steve Youngs.  Of course anyone may ask the Project Lead to call a vote.

Mechanics of the Vote
=====================

 1. The votes will be cast via email on the SXEmacs Developers' mailing list, sxemacs-devel@sxemacs.org.

 2. The ballot paper will have the email subject [Vote] Subject of vote. The body of this email will contain the details of the ballot.  The actual questions or points that make up what is being voted on should be in a form that makes it easy to respond to. In other words they should be either multiple choice or yes/no type questions.

 3. Each person wishing to participate in the vote will simply reply once to this email.  The reply or vote must come to the mailing list.

 4. Anyone wishing to abstain need not do anything.  Just don't reply to the ballot email.

 5. There will be a time limit restriction on voting on any matter.  This time limit will be a minimum of one calendar week from the time the vote is declared open.  The vote is declared open with the posting of the initial ballot email (with the subject prefix of [Vote].

Deciding the Outcome
--------------------

As soon as practicable after the vote closes (when the time limit has expired) the SXEmacs Project Lead will tally up all the votes and post the results to the SXEmacs Developers' mailing list, sxemacs-devel@sxemacs.org.  This post will have the email subject [Vote Results] Subject of vote.

The issue will be decided by simple majority.  For a hung vote (no side has a majority) the Project Lead will either decide the outcome, call a postponement, or even call another vote.

Coding Style
************

SXEmacs has two main programming languages, Emacs Lisp, and C, therefore we need two sets of coding styles.

Coding Style -- Emacs Lisp
==========================

Read see (lispref)Style Tips

Please take particular note of...

     Don't make a habit of putting close-parentheses on lines by themselves; Lisp programmers find this disconcerting.  Once in a while, when there is a sequence of many consecutive close-parentheses, it may make sense to split them in one or two significant places.

The only other thing I have to say about lisp coding style is to keep your lines under 80 columns in length.

Coding Style -- C
-----------------

     First off, I'd suggest printing out a copy of the GNU coding standards, and NOT read it.  Burn them, it's a great symbolic gesture.

     -- Linus Torvalds

General C Style
***************

SXEmacs C code follows, to a large degree, the coding style of the Linux Kernel source.  Much of this section is a verbatim copy of ./Documentation/CodingStyle from the Linux kernel sources.

Indentation
===========

Tabs are 8 characters, and thus indentations are also 8 characters. There are heretic movements that try to make indentations 4 (or even 2!) characters deep, and that is akin to trying to define the value of PI to be 3.

Rationale: The whole idea behind indentation is to clearly define where a block of control starts and ends.  Especially when you've been looking at your screen for 20 straight hours, you'll find it a lot easier to see how the indentation works if you have large indentations.

Now, some people will claim that having 8-character indentations makes the code move too far to the right, and makes it hard to read on a 80-character terminal screen.  The answer to that is that if you need more than 3 levels of indentation, you're screwed anyway, and should fix your program.

In short, 8-char indents make things easier to read, and have the added benefit of warning you when you're nesting your functions too deep. Heed that warning.

Don't put multiple statements on a single line unless you have something to hide:

     	if (condition) do_this;
     	  do_something_everytime;

Outside of comments and documentation, spaces are never used for indentation, and the above example is deliberately broken.

Don't leave whitespace at the end of lines.  There is a whitespace.el which you can get from http://www.dsmit.com/lisp/.  Use it.

Breaking long lines and strings
===============================

Coding style is all about readability and maintainability using commonly available tools.

The limit on the length of lines is 80 columns and this is a hard limit.

Statements longer than 80 columns will be broken into sensible chunks. Descendants are always substantially shorter than the parent and are placed substantially to the right. The same applies to function headers with a long argument list. Long strings are as well broken into shorter strings.

     void
     fun(int a, int b, int c)
     {
     	if (condition)
     		printf("Warning this is a very very very long printf with "
     						"3 parameters a: %u b: %u "
     						"c: %u \n", a, b, c);
     	else
     		next_statement;
     }

Placing Braces
==============

The other issue that always comes up in C styling is the placement of braces.  Unlike the indent size, there are few technical reasons to choose one placement strategy over the other, but the preferred way, as shown to us by the prophets Kernighan and Ritchie, is to put the opening brace last on the line, and put the closing brace first, thusly:

     	if (x is true) {
     		we do y
     	}

However, there is one special case, namely functions: they have the opening brace at the beginning of the next line, thus:

     	int function(int x)
     	{
     		body of function
     	}

Heretic people all over the world have claimed that this inconsistency is...  well...  inconsistent, but all right-thinking people know that (a) K&R are right and (b) K&R are right.  Besides, functions are special anyway (you can't nest them in C).

Note that the closing brace is empty on a line of its own, except in the cases where it is followed by a continuation of the same statement, ie a "while" in a do-statement or an "else" in an if-statement, like this:

     	do {
     		body of do-loop
     	} while (condition);

and

     	if (x == y) {
     		..
     	} else if (x > y) {
     		...
     	} else {
     		....
     	}

Naming
======

C is a Spartan language, and so should your naming be.  Unlike Modula-2 and Pascal programmers, C programmers do not use cute names like THISVARIABLEISATEMPORARYCOUNTER.  A C programmer would call that variable TMP, which is much easier to write, and not the least more difficult to understand.

HOWEVER, while mixed-case names are frowned upon, descriptive names for global variables are a must.  To call a global function "foo" is a shooting offense.

GLOBAL variables (to be used only if you _really_ need them) need to have descriptive names, as do global functions.  If you have a function that counts the number of hidden buffers, you should call that count_hidden_buffers() or similar, you should not call it cntbuf().

Encoding the type of a function into the name (so-called Hungarian notation) is brain damaged - the compiler knows the types anyway and can check those, and it only confuses the programmer.  No wonder MicroSoft makes buggy programs.

LOCAL variable names should be short, and to the point.  If you have some random integer loop counter, it should probably be called I. Calling it LOOP_COUNTER is non-productive, if there is no chance of it being mis-understood.  Similarly, TMP can be just about any type of variable that is used to hold a temporary value.

If you are afraid to mix up your local variable names, you have another problem, which is called the function-growth-hormone-imbalance syndrome.  See next.

Functions
=========

Functions should be short and sweet, and do just one thing.  They should fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24, as we all know), and do one thing and do that well.

A function's return type should be put on a line by itself like this:

     int
     main(int argc, char **argv)
     {
     	...
     	...
     }

This also helps things like etags.

The maximum length of a function is inversely proportional to the complexity and indentation level of that function.  So, if you have a conceptually simple function that is just one long (but simple) case-statement, where you have to do lots of small things for a lot of different cases, it's OK to have a longer function.

However, if you have a complex function, and you suspect that a less-than-gifted first-year high-school student might not even understand what the function is all about, you should adhere to the maximum limits all the more closely.  Use helper functions with descriptive names (you can ask the compiler to in-line them if you think it's performance-critical, and it will probably do a better job of it than you would have done).

Another measure of the function is the number of local variables.  They shouldn't exceed 5-10, or you're doing something wrong.  Re-think the function, and split it into smaller pieces.  A human brain can generally easily keep track of about 7 different things, anything more and it gets confused.  You know you're brilliant, but maybe you'd like to understand what you did 2 weeks from now.

Commenting
==========

Comments are good, but there is also a danger of over-commenting. NEVER try to explain HOW your code works in a comment: it's much better to write the code so that the working is obvious, and it's a waste of time to explain badly written code.

Generally, you want your comments to tell WHAT your code does, not HOW.  Also, try to avoid putting comments inside a function body: if the function is so complex that you need to separately comment parts of it, you should probably go back to section on Functions for a while. You can make small comments to note or warn about something particularly clever (or ugly), but try to avoid excess.  Instead, put the comments at the head of the function, telling people what it does, and possibly WHY it does it.

A comment in C looks like /* a comment */.  A comment in C++ looks like // a comment.  Don't get them confused and don't ever use C++ style comments.

This style of commenting in C is acceptable:

     /*
      * A comment style in C that is quite often used
      * for multi-line comments.
      */

Macros
======

Names of macros defining constants and labels in enums are capitalised.

     #define CONSTANT 0x12345

Enums are preferred when defining several related constants.

CAPITALISED macro names are appreciated but macros resembling functions may be named in lower case.

Generally, inline functions are preferable to macros resembling functions.

Macros with multiple statements should be enclosed in a do - while block:

     #define macrofun(a,b,c) 			\
     	do {					\
     		if (a == 5)			\
     			do_this(b,c);		\
     	} while (0)

Things to avoid when using macros:
----------------------------------

 1. macros that affect control flow:

          #define FOO(x)					\
          	do {					\
          		if (blah(x) < 0)		\
          			return -EBUGGERED;	\
          	} while(0)

     is a very bad idea.  It looks like a function call but exits the "calling" function; don't break the internal parsers of those who will read the code.

 2. macros that depend on having a local variable with a magic name:

          #define FOO(val) bar(index, val)

     might look like a good thing, but it's confusing as hell when one reads the code and it's prone to breakage from seemingly innocent changes.

 3. macros with arguments that are used as l-values: FOO(x) = y; will bite you if somebody e.g. turns FOO into an inline function.

 4. forgetting about precedence: macros defining constants using expressions must enclose the expression in parentheses. Beware of similar issues with macros using parameters.

          #define CONSTANT 0x4000
          #define CONSTEXP (CONSTANT | 3)

Further Reading
===============

     The C Programming Language, Second Edition
     by Brian W. Kernighan and Dennis M. Ritchie.
     Prentice Hall, Inc., 1988.
     ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback).
     http://cm.bell-labs.com/cm/cs/cbook/

     The Practice of Programming
     by Brian W. Kernighan and Rob Pike.
     Addison-Wesley, Inc., 1999.
     ISBN 0-201-61586-X.
     http://cm.bell-labs.com/cm/cs/tpop/

GNU manuals - where in compliance with K&R and this text - for cpp, gcc, gcc internals and indent, all available from http://www.gnu.org/

WG14 is the international standardization working group for the programming language C, http://std.dkuug.dk/JTC1/SC22/WG14/

SXEmacs Specific Style
**********************

This section was lifted almost word for word from the XEmacs CODING-STANDARDS by Ben Wing.

Specially-prefixed functions/variables:
=======================================

  * All global C variables whose value is constant and is a symbol begin with a capital Q, e.g. QKEY_PRESS_EVENT. (The type will always be Lisp_Object.)

  * All other global C variables whose value is a Lisp_Object (this includes variables that forward into Lisp variables plus others like VSELECTED_CONSOLE) begin with a capital V.

  * No C variables whose value is other than a Lisp_Object should begin with a capital V. (This includes C variables that forward into integer or boolean Lisp variables.) All global C variables whose value is a struct Lisp_Subr begin with a capital S. (This only occurs in connection with DEFUN ()).

  * All C functions that are Lisp primitives begin with a capital F, and no others should begin this way.

Functions for manipulating Lisp types:
======================================

  * Any function that creates an empty or mostly empty Lisp object should begin allocate_(). (*Not* make_().) (Except, of course, for Lisp primitives, which usually begin Fmake_()).

  * Any function that converts a pointer into an equivalent Lisp_Object should begin make_().

  * Any function that converts a Lisp_Object into its equivalent pointer and checks the type and validity of the object (e.g. making sure it's not dead) should begin decode_().

  * Any function that looks up a Lisp object (e.g. buffer, face) given a symbol or string should begin get_(). (Except, of course, for Lisp primitives, which usually begin Fget_()).

Other:
======

Any header-file declarations of the sort

        struct foobar;

go into the types section of lisp.h.

Patches
*******

Ideally, the best way to get your patches into the SXEmacs code base is to have Steve fetch them directly from your git repo.  If, for any reason you are not able to set up a repository with read-only access for (at least) Steve, that doesn't mean that you can't still contribute your patches and code.

You can check how to setup a publicly accessible repo at see Setting up a publicly accessible repo.

There are a number of different situations and circumstances that you may find yourself in with regards to contributing to the SXEmacs project.  I'll try to cover the main ones here, but please note that they all have two things in common...

 1. A diff is always sent to SXEmacs Patches.

 2. The diff is always in unified format diff -u oldfile newfile

Sending a patch from a git repo
*******************************

Firstly, if you can set up an accessible remote repo, please do so. You can see how easy it is in section see Setting up a publicly accessible repo.  It will make things so much easier for everyone. We do understand that there may be some valid reasons why you can't, and that is okay, this section still provides a valid workflow.

Before you do anything, we recommend that you run the git-for-steve.sh script which you'll find in the contrib directory.  It will ensure that some basic git config settings are correct, and set up your ``for-steve'' tracking branch.

Preparing a patch from a git repo
---------------------------------

Are you in the right place?  You cloned the SXEmacs sources with git clone http://git.sxemacs.org/sxemacs.

Yes?  OK, great, read on.

Your workflow should run something along these lines...

 1. git pull from your ``for-steve'' branch to sync up with the main SXEmacs repo.

 2. git checkout -b mybugfix to create and checkout a new branch. You can call it whatever you like, just as long as you know what it's about. (Yeah, we recommend that you do all your work on branches and keep your master branch as pristine as possible).

 3. hack hack edit edit fix fix hack

 4. Test!  If all is good, proceed.  If not, return to the previous step.

 5. The next step is to commit your changes, and at this point I'd like to note that, although not mandatory, we encourage and prefer it if you sign all of your commits with GnuPG.  This can be easily set up via git config commit.gpgSign true (Already done for you if you ran the git-for-steve.sh script and it found your key).

     Depending on how you like to deal with change logs, and if the changes were small and trivial or detailed and large:

       * git commit -sam "Summary of changes"  For use with small quick changes that don't really warrant verbose logs to document them.

       * git commit -sa  This form will fire up an editor for you to write your change logs in (You can set which editor to use
          with git config --global core.editor my_fav_editor. Steve has
          his set to a shell function called edit which fires up gnuclient
          if SXEmacs is running, or SXEmacs if not.).

       * git commit -saF mylogfile  Use this form for the times when you have logged your changes as you went to the file mylogfile.

     Please take note, that whichever commit command you use, to always use the -s option to add a Signed-off-by entry to the log.  This will indicate that you played some role in getting the patch into the code base, and, perhaps more importantly, you had permission to do so (There might be licencing/copyright things to be aware of, especially in the case of working on SXEmacs either for your employer, or during your employer's time.).

     For patches that you're submitting to the main SXEmacs code base that have originated from somebody else (maybe you have a small team of sub-developers working for you), the Signed-off-by entry also indicates that you have reviewed, tested, and approved the patch.  And also, the original author has permission to submit it.

 6. git checkout for-steve  To flip back to your for-steve branch.

 7. git merge mybugfix  To merge the changes from the mybugfix branch into your for-steve branch.

     At this point everything that was in the mybugfix branch is now in your for-steve branch, so you no longer need it. You can safely delete it with git branch -d mybugfix.

     Now if you have a publicly accessible repo, you should do:

 8. git push myremote for-steve  To push the changes to your publicly accessible repo, myremote.

If your repos is private, it is safe to skip the push and just advance to the next step.

Patch Submission
----------------

At this point, your changes are ready for Steve to incorporate into the main SXEmacs code base.  All you need to do is let him know, and you can easily do that with the following 2 git commands (The git-for-steve.sh contrib script will set a lot of these for you.):

 1. git format-patch --add-header="X-Git-Repo: REPO-URL" \

     --add-header="X-Git-Branch: for-steve" \

     --subject-prefix="P-Req" --minimal --numbered -o DIR origin/master

 2. git send-email \

     --to="SXEmacs Patches <sxemacs-patches@sxemacs.org>" \

     --from="$(git config user.name) <$(git config user.email)>" DIR

If you not have have a publicly accessible repository, the SXEmacs developers can't pull in your changesets directly from you.  Instead, once your patch hits the mailing list and is approved, it will have to be applied manually to the SXEmacs code base.

You could, in theory, use a post-commit hook, but I'd not recommend it.  Think about the situation where you are working on something fairly big.  You'd most likely commit several times before you have things ready for us.

If you have a publicly accessible repo, be sure to setup automation like in see Automation.

Vanilla sources (no repo)
*************************

Are you in the right place?  All you have is a SXEmacs source tarball and you don't have git installed.

Yes?  OK, great, read on.

You will have the toughest time of it I'm afraid because you will have to do everything manually.  But it isn't too bad.  No worse than for any other project.

Your hacking cycle will look something like this:

 1. Unpack the source tarball somewhere and don't touch it.  This will be your pristine sources.

 2. Make a copy of your pristine sources somewhere else.  This will be your working tree where you make your changes.

 3. cd into your working tree and hack hack hack

 4. Jump out of your working tree and do: diff -urNp pristine-tree working-tree > my-sxemacs.diff

     A note of caution here: Please ensure that you are diff'ing clean trees.  In other words, run make distclean in your working tree before creating the diff.

 5. Send my-sxemacs.diff (gzip'd if large) as a MIME attachment together with a detailed description of your changes to the SXEmacs Patches mailing list.

Feature Requests
****************

From time to time someone will wander into the mailing list or our IRC channel saying something like "ya know, SXEmacs is cool, but it would truly rock if it had fooble-klangers.  How 'bout it guys?  Can somebody please add fooble-klangers to SXEmacs?".

That's a Feature Request.

It doesn't matter what a fooble-klanger is.  It doesn't matter if having said fooble-klanger would make SXEmacs rock or not. What DOES MATTER is that we acknowledge the request.  And we acknowledge it quickly.

So how quick is quickly?  Anything greater than 48 hours is slow. We should try to get an initial ack out within 24 hours of the feature request hitting the mailing list (All legitimate feature requests should eventually end up on the SXEmacs Issue Tracker (http://issues.sxemacs.org/).).  I totally understand that the 24 hour turn-around won't always be possible.  Often there'll be extenuating circumstances (I'm writing this right now in the middle of a 2 week period with no internet connection).

The acknowledgment doesn't need to be anything more than just that, an acknowledgment.  You don't need to have a 100,000 lines of working code that proves how much fooble-klangers make or don't make SXEmacs rock before you let the guy know that he isn't talking to a brick wall.

A feature request can only end up in one of 3 scenarios...

 1. Implemented code.

 2. Discarded idea.

 3. Forgotten about.

Of those, #3 is UNACCEPTABLE!  That means, if you see a feature request that is more than 48 hours old and hasn't been acknowledged, it is YOUR responsibility to do something about it.

A feature request on our Issue Tracker (http://issues.sxemacs.org/) is a issue that has the FeatReq flag set and the severity set to enhancement.

Support Requests
****************

Support requests are a call for help from our users and as such have top priority.  Much of see Feature Requests, applies equally here.

Support requests are everyone's responsibility, so if you see one and you think you can help, do so.

Bug Reports
***********

Bug reports are a good thing.  They show that people are using the code that you spent so much time and effort in writing.  Bug reports are an opportunity to improve SXEmacs.  Never be scared of bug reports.  Never get annoyed or upset by bug reports.  Welcome them. As a matter of fact, worry if you don't see any bug reports.  That would mean we aren't working hard enough. :-)

All bug reports have to be submitted to our Issue Tracker (http://issues.sxemacs.org/).  So it goes without saying that you already have an account on our Issue Tracker, and if you don't, go get one now.

Because the Issue Tracker is just that, it tracks issues, all followups and correspondence concerning a bug must be added via the issue tracker itself.  DO NOT follow up to a bug report on the mailing list.  If a bug report is submitted to the mailing list initially (because the submitter wasn't aware of our Issue Tracker), the person submitting the report should be directed to our Issue Tracker (http://issues.sxemacs.org/).  If they are unwilling or unable to do so, one of us will do so.

If a bug report results in a patch and merge request, the summary of the patch log should contain the text: "(Closes bug #n)", where `n' is the number that our Issue Tracker has assigned to that bug.  The bug should be marked as "fixed" (stating in which revision) on the Issue Tracker.  It should not be marked "Closed" until just prior to a release.  Closing bugs is the job and responsibility of the project lead, or whoever is responsible for making releases.

Making Releases
***************

From time to time, at the project lead's discretion, a release will be made and tarballs created and made available on the SXEmacs download site (http://downloads.sxemacs.org/releases/).

The decision as to when to cut a release is generally influenced by two factors:

 1. How stable the code base is currently.

 2. Whether the changes since the last release warrant a new release.

The minimum number of revisions between releases is one.  The maximum number of revisions between releases is, well, there is no maximum.

The actual steps involved in cutting a release are:

  * Finalise things like...

       * Update etc/NEWS

          To get the numbers for the "Developer Stats" section, first get a list of unique committers for this release with...

          git log --format=full v22.1.15..|grep Author|sort -u

          And then for the number of actual commits for each developer do...

          git log --oneline --no-merges --author=NAME v22.1.15..|wc -l

       * Make sure INSTALL, PROBLEMS etc are up to date.

       * Update sxemacs.texi at...

               It corresponds to: version-string

       * Update the codename and version in autogen.sh

       * Update the versioning macros in this document.

  * Commit those updates.

     git commit -sam "SXEmacs v22.1.16 is released!"

  * Create a new tag which will be the version number of this release.

     git tag -s v22.1.16 -m "SXEmacs v22.1.16"

  * Push it to the public repo.

     git push --tags origin master

  * Prepare tarball:

     (in the release working directory)

          git archive --format=tar \
              --prefix=sxemacs-22.1.16/ HEAD | \
              (cd ~/upload && tar xf -)

  * Clean out the working directory and do autotool preparations.

          HAMMER=1 ./autogen.sh

  * Copy the autotool files to the exported tree

          cp -va libltdl ~/upload/sxemacs-22.1.16 &&
          for f in $(git ls-files --others -i --exclude-standard); do
              cp -va ${f} ~/upload/sxemacs-22.1.16/${f}
          done

  * Add a ChangeLog

          git log --stat v22.1.15..v22.1.16 > ~/upload/sxemacs-22.1.16/ChangeLog

  * Create a diff against the previous version.

              git diff v22.1.15..v22.1.16 > ~/upload/sxemacs-22.1.15-22.1.16.diff

  * Create the tarballs, md5sums, and sigs:

          cd ~/upload
          for compressor in bzip2 gzip lzma xz; do
              ${compressor} --keep sxemacs-22.1.15-22.1.16.diff
          done &&
          for type in bz2 gz lzma xz; do
              tar --create --owner=0 --group=0 --auto-compress --file \
                sxemacs-22.1.16.tar.${type} sxemacs-22.1.16
              md5sum sxemacs-22.1.16.tar.${type} > \
                sxemacs-22.1.16.tar.${type}.md5
              md5sum sxemacs-22.1.15-22.1.16.diff.${type} > \
                sxemacs-22.1.15-22.1.16.diff.${type}.md5
              gpg --detach-sign --armor --output \
                sxemacs-22.1.16.tar.${type}.asc sxemacs-22.1.16.tar.${type}
              gpg --detach-sign --armor --output \
                sxemacs-22.1.15-22.1.16.diff.${type}.asc \
                sxemacs-22.1.15-22.1.16.diff.${type}
          done

  * Move the tarballs, diffs, GnuPG sigs, and md5sums to SXEmacs Download Site (http://downloads.sxemacs.org/releases/).

          for file in *.{bz2,gz,lzma,xz,md5,asc}; do
              scp ${file} downloads.sxemacs.org:downloads.sxemacs.org/releases
          done

  * Rename the LATEST-IS-VER file.

          ssh downloads.sxemacs.org \
            mv downloads.sxemacs.org/releases/LATEST-IS-{22.1.15,22.1.16}

  * Update www.sxemacs.org:

       * Update download.html

       * Add ChangeLog-22.1.16 to the website

       * Update index.html

  * Send a release announcement to SXEmacs Devel and comp.emacs.xemacs.

  * Commit the first patch to the next version, which would be adding a ChangeLog.d/ChangeLog-22.1.16

New Features
************

How do you get a new feature into SXEmacs?  It's not hard, but remember this, we look at any new feature in this order of priority...

 1. Tested working code.

 2. A plan of action with Proof of concept code.

 3. A plan of action with a willingness to write the code.

 4. An idea with a willingness to move it to a real plan and then to code.

 5. An idea with a willingness to help test any code resulting from it.

 6. ``Hey, wouldn't it be cool if...''

Don't be disheartened if you aren't a master programmer, quite often the best new features and ideas come from non-programmers.  All too often the people writing the code get caught up in what they are doing and find it hard to see things from outside of the box.  Anyone can help with ideas and with testing new code and features.

Any new feature begins with an idea, and at that point somebody should post that idea to SXEmacs Devel.

Compatibility
*************

All I'll say about this is that for the foreseeable future, SXEmacs will remain 100% backwardly compatible with XEmacs where emacs lisp is concerned.  An emacs lisp package or library that runs on XEmacs will run on SXEmacs.

If you find a place where this isn't true, you should report it as a bug, see Bug Reports.

If you find areas where SXEmacs is incompatible with GNU/Emacs at the emacs lisp level, that is an issue between GNU/Emacs and XEmacs.  That doesn't mean that we won't ever port GNU/Emacs things to SXEmacs, we'll just do it in a way that doesn't break compatibility with XEmacs.

Copyright and Licencing
***********************

SXEmacs is an Open Source project.  Because of that we can only accept code and contributions that are covered by an Open Source licence.

We differ from the GNU/Emacs project in that we will accept any OSI approved Open Source licence, not just the GNU GPL.  That means that if you are more comfortable with, say, the BSD licence, that's cool by us.

We also won't ask you to reassign your copyright to anyone else.  If you want to reassign your copyright to the FSF (for example), you can, but we won't reject any contributions from you because you haven't. (If you contribute code to SXEmacs that you want included in GNU/Emacs you will have to reassign copyright to the FSF.  Please understand that that is a GNU/Emacs requirement and not a SXEmacs requirement)

SXEmacs and your Employer
-------------------------

This is very important.  If you write code for SXEmacs either on your employer's time (while you are at work), or using your employer's resources (hardware, software, electricity, furniture, etc) then your employer may have legal copyright of your work.

PLEASE be up front with your employer and clear it with them before you write anything for SXEmacs.  It is OK and perfectly acceptable to submit contributions to SXEmacs that are copyrighted to your employer, providing (and this is the key) your employer is willing to release the code under an approved OSI licence.

Don't overlook or dismiss this.  It is here to safeguard you, your employer, the SXEmacs project as a whole, and Steve Youngs personally.

Documentation Licences
----------------------

Please don't licence any documentation under the FSF's new Free Documentation Licence.  This isn't a slight against the FSF or the GNU project, it is just because it will mean that our documentation would not be able to be included in XEmacs.  It may even cause problems going the other way as well (XEmacs to SXEmacs).

For that reason, we'll err on the side of caution.

Developer Recruitment
*********************

We don't actively try to recruit new developers in any kind of formal way.  What we do is use SXEmacs for everything everyday and not hide the fact that we do. :-)  That in itself makes people curious and some ask about this thing called SXEmacs.  Show them what it is, point them to the web site (http://www.sxemacs.org/), encourage them to subscribe to SXEmacs Devel, and even help them get an account on Our Issue Tracker (http://issues.sxemacs.org/).  And low and behold!  We have a new developer.

One recruitment tool that we do have is sxemacs.org email addresses.  If you'd like one, contact Steve Youngs.  Then you can use that email address whenever and whereever you like.  Hmm, perhaps not everywhere, it might not look so good if you use it for log in details to a pr0n site. :-P

Making/Altering Policies
************************

How do you get these policies and proceedures changed?  Simple.  Just post to SXEmacs Devel stating where what how when and why.  If it is non-controversial and makes sense, it'll probably be accepted quickly.  If not, there could be lengthy discussions and possibly even a vote see Voting.

Steve Youngs will always have the final word and make the ultimate decision, but he isn't an immovable force, his mind can be changed and he does listen to what the rest of the project is saying. :-)

Version Control
***************

The SXEmacs Project keeps control of its sources with git, starting with version 22.1.13. The main repository is that of the Project Lead (Steve Youngs).  It is located at:

       http://git.sxemacs.org/sxemacs

Checking out a copy of SXEmacs is as easy as:

       git clone http://git.sxemacs.org/sxemacs

The chapter on patches see Patches will show you how to prepare and send in your contributions.

Setting up a publicly accessible repo
*************************************

You only need to read this section if you are able to host a publicly accessible repo somewhere.

Getting everything set up is really very easy.  I think you'll be quite surprised if you haven't done this sort of thing before.  In the examples below I'm assuming that you have shell access to your remote host via ssh...

     user@localhost ~ $ ssh user@your.host
     user@host ~ $ mkdir -v sxemacs
     user@host ~ $ cd !$
     user@host ~/sxemacs $ git init --bare
     user@host ~/sxemacs $ echo Your Name's SXEmacs Repo > description
     user@host ~/sxemacs $ exit
     user@localhost ~ $ git clone http://git.sxemacs.org/sxemacs
     user@localhost ~ $ cd sxemacs
     user@localhost ~/sxemacs $ contrib/git-for-steve.sh

And that's it!  Told you it was easy, didn't I?  All you have to do now is push your local copy to your remote...

     git push MYREMOTE master

Automation
==========

The last two commands for patch submission listed in see Patch Submission, format-patch and send-email are fairly long and hairy.  You'd no doubt have trouble remembering them.  But, never fear, git has a few tricks up her sleeve to make your life easier.

Automating with Hooks
---------------------

If you are lucky enough to NOT be using github (github is great and may be the ideal solution for you to host your repo somewhere, but it is inflexible in that you get no shell access, you can't set up custom hooks, and you are very limited in what git config settings you can tweak.) to host your publicly accessible repo you can set up a post-receive hook to automatically send your pull requests to the SXEmacs mailing list when you push to it.

Setting Up The post-receive Hook
--------------------------------

Remember: This hook runs from your publicly accessible repo (your remote), and NOT from your local working directory.  It is called after you push to your remote.

Jump over to your remote now and follow these steps

 1. Take a look in the file hooks/post-receive.sample.  At the bottom of that file there is a commented line, that when uncommented would call another script, post-receive-email.  Check that the path is correct, and uncomment it.

 2. Rename hooks/post-receive.sample to hooks/post-receive

 3. Tweak the remote's config with...

          git config hooks.mailinglist \
              "SXEmacs Patches <sxemacs-patches@sxemacs.org>"
          git config hooks.envelopesender "Your Name <your@email>"
          git config hooks.emailprefix "[P-Req] "
          git config hooks.showrev "git show -C %s; echo"

 4. echo "Your Name's SXEmacs Repo" > description

Take note that the SXEmacs mailing lists will funnel any post from non-subscribers into the moderation queue.  So make sure that the address you set hooks.envelopesender to is subscribed to the patches list.

Also be aware that using this post-receive hook will mean that every time you push to your publicly accessible repo, a message will be sent to sxemacs-patches; this includes instances where you merely are pulling the latest from mainline and mirroring. Hence, the use of aliases as discussed below may be preferable.  We are looking into ways of avoiding this sort of annoyance.

Automating with Aliases
-----------------------

Git allows you to define aliases that will let you do all kinds of funky things.  Remember those hairy format-patch and send-email commands?

     git config alias.sxe-fp 'format-patch --add-header="X-Git-Repo: REPO-URL" \
         --subject-prefix="P-Req" --numbered'

     git config alias.sxe-sm 'send-email \
         --to="SXEmacs Patches <sxemacs-patches@sxemacs.org>" \
         --from="$(git config user.name) <$(git config user.email)>"'

With those 2 aliases set you can get your pull requests in by doing...

git sxe-fp -o DIR origin && git sxe-sm DIR

Making Life Even Easier with git config
---------------------------------------

You can make your life even easier by having git store things in its config.  In this case, you can store those format-patch and send-email command line options in the repo's config...

     git config format.headers "X-Git-Repo: YOUR-REMOTE-URL"
     git config format.subjectprefix "P-Req"
     git config format.numbered true

     git config sendemail.to \
         "SXEmacs Patches <sxemacs-patches@sxemacs.org>"
     git config sendemail.from "Your Name <your@email>"

With those settings, the commands: git format-patch -o DIR origin, and git send-email DIR are now equivalent of the original long hairy ones mentioned further up.

Be careful when setting up aliases and config settings that you only make them global if you absolutely have to.  All the ones I've shown here have been repo-specific.

The git-for-steve.sh script in our contrib directory is an easy (and recommended) way to set up your git repo.  It'll make sure that you have everything set up correctly and in an optimal way.

Setting up a private repos
**************************

Git makes it as easy to create a private repo as getting a checkout of the source code. In fact, that is all you have to do.

       git clone http://git.sxemacs.org/sxemacs

You may want to follow some of the steps in see Automating with Aliases, to ease your life when sending patches if you plan to contribute frequently from this repo. Please note that in this case you should not reference any REPO-URL.

However if you do plan to contribute frequently, we strongly suggest you configure a publicly accessible repos.

More details at see Setting up a publicly accessible repo.

Other Developers' Repositories
******************************

As previously mentioned, the master SXEmacs repo is at:

       http://git.sxemacs.org/sxemacs

Some of these repos may not be publicly accessible or may not be accessible 24/7.

     Nelson

  * http://git.nelsonferreira.com/sxemacs Horst

  * http://midcom.steveyoungs.com/oss-vc/sxemacs.git lg

  * git://github.com/zevlg/SXEmacs.git Rudi

  * git://github.com/rudimeier/sxemacs.git Aidan

  * http://bitbucket.org/kehoea/sxemacs/ Sebastian

  * git://github.com/hroptatyr/sxemacs.git

And of course the main repo (Steve's) is at:

http://git.sxemacs.org/sxemacs http://git.sxemacs.org/website  (our website is under git too)

The tla repository for versions upto 22.1.12
--------------------------------------------

The old tla repos at http://arch.sxemacs.org/2010 still exist, and will remain forever.  If you ever need anything from them just install tla and leech them with that.

The reason we are keeping them around indefinitely is because the move to git meant a loss of history.  There are tools available for converting a arch repo to git, but they failed to work in our case because of the cached revisions in our repos.