4 @settitle SXEmacs Policies & Procedures Manual
9 @c Define a macro or 2 (abbrevs)
19 Copyright @copyright{} 2004 - 2016 @sy{}
23 @email{steve@@sxemacs.org, @sy{}}
36 @set UPDATED June 13, 2015
38 @c Things would be a lot easier if everything supported the `@copying'
39 @c command, I wouldn't have to put in these conditionals. --SY.
42 This is the SXEmacs Policies & Procedures Manual.
43 It was last updated @value{UPDATED}.
48 Permission is granted to copy, distribute and/or modify this document
49 under the terms of the GNU General Public Licence, Version 2.
51 Permission is granted to copy and distribute translations of this manual
52 into another language, under the above conditions for modified versions.
56 Permission is granted to process this file through Tex and print the
57 results, provided the printed document carries copying permission
58 notice identical to this one except for the removal of this paragraph
59 (this paragraph not being relevant to the printed manual).
64 @dircategory SXEmacs Development
66 * SPPM:: SXEmacs Policies & Procedures Manual.
70 @title SXEmacs Policies & Procedures Manual
71 @subtitle @value{EDITION} edition, last updated on @value{UPDATED}.
72 @vskip 0pt plus 1filll
77 This is the SXEmacs Policies & Procedures Manual.
78 It was last updated @value{UPDATED}.
83 Permission is granted to copy, distribute and/or modify this document
84 under the terms of the GNU General Public Licence, Version 2.
86 Permission is granted to copy and distribute translations of this manual
87 into another language, under the above conditions for modified versions.
91 Permission is granted to process this file through Tex and print the
92 results, provided the printed document carries copying permission
93 notice identical to this one except for the removal of this paragraph
94 (this paragraph not being relevant to the printed manual).
99 @c Set up the headers and footers for the printed output (postscript).
101 @everyheading @thischapter @|@| @thispage
102 @everyfooting @thistitle @|@| @syc{}
106 @node Top, Mission Statement, (dir), (dir)
109 This is the @value{EDITION} edition of the @cite{SXEmacs Policies & Procedures Manual}
116 This document, as its name implies, is directed towards anyone who is
117 actively involved (or thinking of becoming actively involved) in the
118 development of @uref{http://www.sxemacs.org/, SXEmacs}.
121 * Mission Statement:: Why we do what we do
122 * Online Presence:: Where we make our first impressions
123 * Dispute Resolution:: Arguments can be resolved
124 * Coding Style:: Making sure your code looks like our code
125 * Patches:: Handling contributed code/docs
126 * Feature Requests:: Dealing with feature requests
127 * Support Requests:: Handling support requests
128 * Bug Reports:: Dealing with bug reports
129 * Making Releases:: Getting the finished product to the user
130 * New Features:: Getting new stuff into the code base
131 * Compatibility:: With XEmacs and GNU/Emacs
132 * Copyright and Licencing:: We won't accept just any old licence
133 * Developer Recruitment:: How to get new blood
134 * Making/Altering Policies:: Changing or updating this document
135 * Version Control:: How we keep track of the source
136 * Concept Index:: Concept Index
139 @node Mission Statement, Online Presence, Top, Top
140 @chapter SXEmacs Mission Statement
141 @cindex mission statement
145 Our mission is to@dots{}
148 To provide the Open Source community with a text editing and development
149 environment that is based on XEmacs and is 2nd to none in regards to
150 stability, features, and innovation.
152 To foster a user and developer friendly project environment.
154 And, above all, to have fun doing it.
157 @node Online Presence, Dispute Resolution, Mission Statement, Top
158 @comment node-name, next, previous, up
159 @chapter SXEmacs' Online Presence
165 @cindex sxemacs online
166 @cindex online, sxemacs
168 The SXEmacs project maintains a number of @dfn{online} services.
173 @uref{http://www.sxemacs.org/, The SXEmacs Web Site}
175 @uref{http://downloads.sxemacs.org/, Release and Snapshot Tarballs}
177 @uref{irc://irc.freenode.net/#sxemacs, The SXEmacs IRC channel}
179 @uref{http://issues.sxemacs.org/, The SXEmacs Issue Tracker} @ref{Bug Reports}
180 @ref{Feature Requests} @ref{Support Requests}.
182 @uref{http://store.sxemacs.org/, SXEmacs Merchandise}
186 * Web Site:: Our shop front
187 * Download Site:: Where we keep the tarballs
188 * IRC:: For those who like to talk about it
189 * Merchandise:: Got the software@dots{} Get the T-Shirt
192 @node Web Site, Download Site, Online Presence, Online Presence
193 @comment node-name, next, previous, up
194 @chapter SXEmacs Web Site
197 @cindex www.sxemacs.org
199 The SXEmacs web site content is kept under the same version control
200 system as SXEmacs itself @ref{Version Control}. That means that
201 anyone can submit changes and updates to the site in the same manner
202 that they would for code submissions to SXEmacs @xref{Patches}.
204 There's really not much more to tell about the web site. It is just
205 your normal run-of-the-mill web site. And as everyone knows, HTML
206 blows goats so it doesn't get updated anywhere near as often as it
207 should. We do have a @email{webmaster@@sxemacs.org, Webmaster}, so if
208 you do have any comments about the site, you should direct them there.
209 Or, alternatively, @email{sxemacs-devel@@sxemacs.org, SXEmacs Devel}
212 @node Download Site, IRC, Web Site, Online Presence
213 @comment node-name, next, previous, up
214 @chapter SXEmacs Download Site
221 @uref{http://downloads.sxemacs.org/releases/, SXEmacs release downloads} is
222 where you'll find release tarballs and release to release patches
223 available for download.
225 @uref{http://downloads.sxemacs.org/snapshots/, SXEmacs snapshot downloads}
226 is where you can find snapshot tarballs which are uploaded from time
227 to time. Please note that these snapshots can sometimes be very
230 If you would like something made available for download at the SXEmacs
231 download site, contact @sye{}.
233 @node IRC, Merchandise, Download Site, Online Presence
234 @comment node-name, next, previous, up
235 @chapter SXEmacs on IRC
241 Developers official communcation platform is the mailing list provided
242 at sxemacs.org. However, to discuss problems and assist users more
243 efficiently there is an official IRC channel.
245 SXEmacs IRC channel @dfn{#sxemacs} is located at freenode (formerly
246 known as OPN). Please use following URI to refer to it:
248 @uref{irc://irc.freenode.net/#sxemacs}
250 @subheading Various IRC HowTOs
254 Connecting to the network and joining the channel
256 Fire up your favourite irc client and use:
257 @code{/server irc.freenode.net} to connect to the network and
258 @code{/join #sxemacs} to join the community.
260 HowTo become a respected regular
262 Okay, you've decided to be active on IRC and hopefully help other
263 users. You have joined the channel and idle around thirsting for hard
264 problems by helpless users.
266 In that case you will have to have a reliable (not-changing) nickname
267 that is linked to your person in order to refer to you. This will help
268 us in blaming you if you misdirect users with your answers and even help
269 us to praise you if you convinced RMS to switch to SXEmacs ;)
271 Therefore, freenode provides a mechanism to eternalise yourself via
272 the nickname you carry. Use @code{/nickserv register <password>}
273 to engrave your nickname for your personal use.
275 This nickname is yours from now on. To identify yourself to freenode
276 use @code{/nickserv identify <samepasswordasabove>}
278 Your user mode will be changed to @dfn{+e} in case of successful
281 Whenever you see unscrupulous people carrying your nickname or your
282 nickname is ghosted because of a reconnection, you can just
283 @code{/nickserv ghost <yournickname> <yourpassword>} to send the
284 other client to oblivion.
286 Okay, now that you've registered yourself with freenode, you're
287 nickname can be referred to, independently from whether you are
288 carrying that nick or not. Just do @code{/nickserv info <nickname>}
289 to obtain some information on a nickname you see and like to refer
292 HowTo to be listed in the channel access list
294 There is no influence on this access list on the users and developer's
295 side. It is merely up to the project lead who has control over it.
299 The only way to get one is to ask the project lead (SteveYoungs).
303 You don't have an IRC client but still want to shoot the breeze with
304 us on IRC? Then we have an answer for you@dots{}
305 @uref{http://www.sxemacs.org/irc.html, Chat from the web}.
308 @node Merchandise,, IRC, Online Presence
309 @comment node-name, next, previous, up
310 @chapter SXEmacs Merchandise
317 @cindex retail therapy
322 At @uref{http://store.sxemacs.org/, The SXEmacs Store} you will find
323 for sale various cool and sexy goodies sporting the SXEmacs logo. The
324 proceeds from all purchases go toward covering the costs involved in
325 the upkeep of the SXEmacs project. Be the first on your street to own
326 a @i{I'm Too Sexy For My Emacs} T-shirt!
328 @node Dispute Resolution, Coding Style, Online Presence, Top
329 @comment node-name, next, previous, up
330 @chapter Dispute Resolution
331 @cindex dispute resolution
332 @cindex resolution, dispute
333 @cindex resolving disputes
334 @cindex disputes, resolving
339 When two people agree on everything, one of them isn't needed.
342 I can't remember where that quote comes from so if anyone reading this
343 knows, please let us know so we can give credit where credit is due.
345 We are all mature adults and most of the time we don't let our egos get
346 in the way of getting things done. But human nature being what it is
347 means that from time to time we'll have conflict or disagreements. In
348 the vast majority of these cases a resolution will come quickly and
349 easily through reasonable discussion.
351 This section is for those rare occasions that will be the exception to
354 In the event of a unresolvable dispute, the SXEmacs Project Lead,
355 @sye{}, will, at his discretion, take one or more of the following
362 Call a @dfn{vote} @ref{Voting}.
364 Call a @dfn{postponement}. This will mean that all parties will be
365 asked to stop discussing the matter until some date in the future. This
366 future date will be given at the time the SXEmacs Project Lead calls the
367 postponement. The idea here is to give everyone a chance to cool down
368 so that reasonable discussion can continue.
371 To date, we've not ever had to resort to these. We tend to sort
372 things out pretty quickly and amicably most of the time.
375 * Voting:: Deciding things via ballot
378 @node Voting,, Dispute Resolution, Dispute Resolution
379 @comment node-name, next, previous, up
385 Sometimes things are best decided with a vote. This section describes
386 how these votes are to be held.
388 Who may participate in a vote? Anyone subscribed to the SXEmacs
389 Developers' mailing list, @email{sxemacs-devel@@sxemacs.org}.
391 Who may call a vote? The SXEmacs Project Lead, @sye{}. Of course
392 anyone may ask the Project Lead to call a vote.
394 @section Mechanics of the Vote
398 The votes will be cast via email on the SXEmacs Developers' mailing
399 list, @email{sxemacs-devel@@sxemacs.org}.
401 The @dfn{ballot paper} will have the email subject
402 @dfn{[Vote] Subject of vote}. The body of this email will contain the
403 details of the ballot. The actual questions or points that make up what
404 is being voted on should be in a form that makes it easy to respond to.
405 In other words they should be either multiple choice or yes/no type
408 Each person wishing to participate in the vote will simply reply
409 @emph{once} to this email. The reply or @dfn{vote} @emph{must} come to
412 Anyone wishing to abstain need not do anything. Just don't reply to the
415 There will be a time limit restriction on voting on any matter. This
416 time limit will be a minimum of one calendar week from the time the vote
417 is declared @dfn{open}. The vote is declared @dfn{open} with the
418 posting of the initial ballot email (with the subject prefix of
423 @subsection Deciding the Outcome
425 As soon as practicable after the vote closes (when the time limit has
426 expired) the SXEmacs Project Lead will tally up all the votes and post
427 the results to the SXEmacs Developers' mailing list,
428 @email{sxemacs-devel@@sxemacs.org}. This post will have the email
429 subject @dfn{[Vote Results] Subject of vote}.
431 The issue will be decided by simple majority. For a hung vote (no
432 side has a majority) the Project Lead will either decide the outcome,
433 call a postponement, or even call another vote.
435 @node Coding Style, Patches, Dispute Resolution, Top
436 @comment node-name, next, previous, up
437 @chapter Coding Style
439 @cindex style, coding
443 SXEmacs has two main programming languages, Emacs Lisp, and C, therefore
444 we need two sets of coding styles.
446 @section Coding Style -- Emacs Lisp
447 @cindex emacs lisp coding style
448 @cindex coding style, emacs lisp
449 @cindex lisp coding style
450 @cindex coding style, lisp
452 Read @pxref{(lispref)Style Tips}
454 Please take particular note of@dots{}
457 Don't make a habit of putting close-parentheses on lines by
458 themselves; Lisp programmers find this disconcerting. Once in a
459 while, when there is a sequence of many consecutive
460 close-parentheses, it may make sense to split them in one or two
464 The only other thing I have to say about lisp coding style is to keep
465 your lines @emph{under} 80 columns in length.
467 @subsection Coding Style -- C
468 @cindex C coding style
469 @cindex coding style, C
472 First off, I'd suggest printing out a copy of the GNU coding standards,
473 and NOT read it. Burn them, it's a great symbolic gesture.
479 * General C Style:: What you should use everywhere
480 * SXEmacs Specific Style:: Our idiosyncrasies
483 @node General C Style, SXEmacs Specific Style, Coding Style, Coding Style
484 @chapter General C Style
485 @cindex C coding style
486 @cindex coding style, C
487 @cindex general coding style
488 @cindex coding style, general
490 SXEmacs C code follows, to a large degree, the coding style of the Linux
491 Kernel source. Much of this section is a verbatim copy of
492 @file{./Documentation/CodingStyle} from the Linux kernel sources.
496 @cindex indentation coding style
497 @cindex coding style, indentation
499 Tabs are 8 characters, and thus indentations are also 8 characters.
500 There are heretic movements that try to make indentations 4 (or even 2!)
501 characters deep, and that is akin to trying to define the value of PI to
504 Rationale: The whole idea behind indentation is to clearly define where
505 a block of control starts and ends. Especially when you've been looking
506 at your screen for 20 straight hours, you'll find it a lot easier to see
507 how the indentation works if you have large indentations.
509 Now, some people will claim that having 8-character indentations makes
510 the code move too far to the right, and makes it hard to read on a
511 80-character terminal screen. The answer to that is that if you need
512 more than 3 levels of indentation, you're screwed anyway, and should
515 In short, 8-char indents make things easier to read, and have the added
516 benefit of warning you when you're nesting your functions too deep.
519 Don't put multiple statements on a single line unless you have something
523 if (condition) do_this;
524 do_something_everytime;
527 Outside of comments and documentation, spaces are never used for
528 indentation, and the above example is deliberately broken.
530 @cindex coding style, whitespace
532 Don't leave whitespace at the end of lines. There is a
533 @file{whitespace.el} which you can get from
534 @uref{http://www.dsmit.com/lisp/}. Use it.
536 @heading Breaking long lines and strings
538 Coding style is all about readability and maintainability using commonly
541 The limit on the length of lines is 80 columns and this is a hard limit.
543 Statements longer than 80 columns will be broken into sensible chunks.
544 Descendants are always substantially shorter than the parent and are placed
545 substantially to the right. The same applies to function headers with a long
546 argument list. Long strings are as well broken into shorter strings.
550 fun(int a, int b, int c)
553 printf("Warning this is a very very very long printf with "
554 "3 parameters a: %u b: %u "
555 "c: %u \n", a, b, c);
561 @heading Placing Braces
563 @cindex coding style, braces
564 The other issue that always comes up in C styling is the placement of
565 braces. Unlike the indent size, there are few technical reasons to
566 choose one placement strategy over the other, but the preferred way, as
567 shown to us by the prophets Kernighan and Ritchie, is to put the opening
568 brace last on the line, and put the closing brace first, thusly:
576 However, there is one special case, namely functions: they have the
577 opening brace at the beginning of the next line, thus:
586 Heretic people all over the world have claimed that this inconsistency
587 is@dots{} well@dots{} inconsistent, but all right-thinking people know that
588 (a) K&R are @emph{right} and (b) K&R are right. Besides, functions are
589 special anyway (you can't nest them in C).
591 Note that the closing brace is empty on a line of its own, @emph{except}
592 in the cases where it is followed by a continuation of the same statement,
593 ie a "while" in a do-statement or an "else" in an if-statement, like this:
598 @} while (condition);
606 @} else if (x > y) @{
615 @cindex coding style, naming
616 C is a Spartan language, and so should your naming be. Unlike Modula-2
617 and Pascal programmers, C programmers do not use cute names like
618 @var{ThisVariableIsATemporaryCounter}. A C programmer would call that
619 variable @var{tmp}, which is much easier to write, and not the least more
620 difficult to understand.
622 HOWEVER, while mixed-case names are frowned upon, descriptive names for
623 global variables are a must. To call a global function "foo" is a
626 GLOBAL variables (to be used only if you _really_ need them) need to
627 have descriptive names, as do global functions. If you have a function
628 that counts the number of hidden buffers, you should call that
629 @code{count_hidden_buffers()} or similar, you should @emph{not} call it
632 Encoding the type of a function into the name (so-called Hungarian
633 notation) is brain damaged - the compiler knows the types anyway and can
634 check those, and it only confuses the programmer. No wonder MicroSoft
635 makes buggy programs.
637 LOCAL variable names should be short, and to the point. If you have
638 some random integer loop counter, it should probably be called @var{i}.
639 Calling it @var{loop_counter} is non-productive, if there is no chance
640 of it being mis-understood. Similarly, @var{tmp} can be just about any
641 type of variable that is used to hold a temporary value.
643 If you are afraid to mix up your local variable names, you have another
644 problem, which is called the @dfn{function-growth-hormone-imbalance
649 @cindex coding style, functions
650 Functions should be short and sweet, and do just one thing. They should
651 fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
652 as we all know), and do one thing and do that well.
654 A function's return type should be put on a line by itself like this:
658 main(int argc, char **argv)
665 This also helps things like @code{etags}.
667 The maximum length of a function is inversely proportional to the
668 complexity and indentation level of that function. So, if you have a
669 conceptually simple function that is just one long (but simple)
670 case-statement, where you have to do lots of small things for a lot of
671 different cases, it's OK to have a longer function.
673 However, if you have a complex function, and you suspect that a
674 less-than-gifted first-year high-school student might not even
675 understand what the function is all about, you should adhere to the
676 maximum limits all the more closely. Use helper functions with
677 descriptive names (you can ask the compiler to in-line them if you think
678 it's performance-critical, and it will probably do a better job of it
679 than you would have done).
681 Another measure of the function is the number of local variables. They
682 shouldn't exceed 5-10, or you're doing something wrong. Re-think the
683 function, and split it into smaller pieces. A human brain can
684 generally easily keep track of about 7 different things, anything more
685 and it gets confused. You know you're brilliant, but maybe you'd like
686 to understand what you did 2 weeks from now.
691 @cindex coding style, commenting
692 @cindex coding style, comments
693 Comments are good, but there is also a danger of over-commenting.
694 @emph{NEVER} try to explain @emph{HOW} your code works in a comment:
695 it's much better to write the code so that the @emph{working} is
696 obvious, and it's a waste of time to explain badly written code.
698 Generally, you want your comments to tell @emph{WHAT} your code does, not
699 @emph{HOW}. Also, try to avoid putting comments inside a function body:
700 if the function is so complex that you need to separately comment parts of
701 it, you should probably go back to section on @dfn{Functions} for a while.
702 You can make small comments to note or warn about something particularly
703 clever (or ugly), but try to avoid excess. Instead, put the comments at
704 the head of the function, telling people what it does, and possibly WHY it
707 A comment in C looks like @code{/* a comment */}. A comment in C++
708 looks like @code{// a comment}. Don't get them confused and don't
709 @emph{ever} use C++ style comments.
711 This style of commenting in C @emph{is} acceptable:
715 * A comment style in C that is quite often used
716 * for multi-line comments.
723 @cindex coding style, macros
724 Names of macros defining constants and labels in enums are capitalised.
727 #define CONSTANT 0x12345
730 Enums are preferred when defining several related constants.
732 CAPITALISED macro names are appreciated but macros resembling functions
733 may be named in lower case.
735 Generally, inline functions are preferable to macros resembling functions.
737 Macros with multiple statements should be enclosed in a do - while block:
740 #define macrofun(a,b,c) \
747 @subheading Things to avoid when using macros:
751 macros that affect control flow:
761 is a @emph{very} bad idea. It looks like a function call but exits the "calling"
762 function; don't break the internal parsers of those who will read the code.
765 macros that depend on having a local variable with a magic name:
768 #define FOO(val) bar(index, val)
771 might look like a good thing, but it's confusing as hell when one reads the
772 code and it's prone to breakage from seemingly innocent changes.
775 macros with arguments that are used as l-values: FOO(x) = y; will
776 bite you if somebody e.g. turns FOO into an inline function.
779 forgetting about precedence: macros defining constants using expressions
780 must enclose the expression in parentheses. Beware of similar issues with
781 macros using parameters.
784 #define CONSTANT 0x4000
785 #define CONSTEXP (CONSTANT | 3)
789 @heading Further Reading
790 @cindex further reading
791 @cindex coding style, further reading
793 The C Programming Language, Second Edition
794 by Brian W. Kernighan and Dennis M. Ritchie.
795 Prentice Hall, Inc., 1988.
796 ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback).
797 @uref{http://cm.bell-labs.com/cm/cs/cbook/}
799 The Practice of Programming
800 by Brian W. Kernighan and Rob Pike.
801 Addison-Wesley, Inc., 1999.
803 @uref{http://cm.bell-labs.com/cm/cs/tpop/}
806 GNU manuals - where in compliance with K&R and this text - for cpp, gcc,
807 gcc internals and indent, all available from @uref{http://www.gnu.org/}
809 WG14 is the international standardization working group for the programming
810 language C, @uref{http://std.dkuug.dk/JTC1/SC22/WG14/}
812 @node SXEmacs Specific Style,,General C Style, Coding Style
814 @chapter SXEmacs Specific Style
815 @cindex sxemacs specific coding style
816 @cindex coding style, sxemacs specific
818 This section was lifted almost word for word from the XEmacs
819 @file{CODING-STANDARDS} by Ben Wing.
821 @heading Specially-prefixed functions/variables:
822 @cindex coding style, function prefix
823 @cindex coding style, variable prefix
824 @cindex coding style, functions
825 @cindex coding style, variables
828 All global C variables whose value is constant and is a symbol begin
829 with a capital Q, e.g. @var{Qkey_press_event}. (The type will always be
833 All other global C variables whose value is a @dfn{Lisp_Object} (this
834 includes variables that forward into Lisp variables plus others like
835 @var{Vselected_console}) begin with a capital V.
838 No C variables whose value is other than a @dfn{Lisp_Object} should begin
839 with a capital V. (This includes C variables that forward into
840 integer or boolean Lisp variables.)
841 All global C variables whose value is a struct Lisp_Subr begin with a
842 capital S. (This only occurs in connection with DEFUN ()).
845 All C functions that are Lisp primitives begin with a capital F,
846 and no others should begin this way.
849 @heading Functions for manipulating Lisp types:
850 @cindex coding style, functions
853 Any function that creates an empty or mostly empty Lisp object
854 should begin allocate_(). (*Not* make_().) (Except, of course,
855 for Lisp primitives, which usually begin Fmake_()).
858 Any function that converts a pointer into an equivalent Lisp_Object
859 should begin make_().
862 Any function that converts a Lisp_Object into its equivalent pointer
863 and checks the type and validity of the object (e.g. making sure
864 it's not dead) should begin decode_().
867 Any function that looks up a Lisp object (e.g. buffer, face) given
868 a symbol or string should begin get_(). (Except, of course, for
869 Lisp primitives, which usually begin Fget_()).
874 Any header-file declarations of the sort
880 go into the @dfn{types} section of @file{lisp.h}.
883 @node Patches, Feature Requests, Coding Style, Top
884 @comment node-name, next, previous, up
887 @cindex contributions
891 Ideally, the best way to get your patches into the SXEmacs code base is
892 to have @s{} fetch them directly from your git repo. If, for any
893 reason you are not able to set up a repository with read-only access
894 for (at least) @s{}, that doesn't mean that you can't still contribute
895 your patches and code.
897 You can check how to setup a publicly accessible repo at @xref{Setting
898 up a publicly accessible repo}.
900 There are a number of different situations and circumstances that you
901 may find yourself in with regards to contributing to the SXEmacs
902 project. I'll try to cover the main ones here, but please note that
903 they @emph{all} have two things in common@dots{}
907 A diff is always sent to
908 @email{sxemacs-patches@@sxemacs.org, SXEmacs Patches}.
910 The diff is always in @dfn{unified} format
911 @code{diff -u oldfile newfile}
915 * Sending a patch from a git repo::
916 Procedure to send a patch from a git repo,
917 be it a publicly accessible one, or just a
918 private clone from the master repo.
919 * Vanilla sources (no repo):: Just the source tree that isn't under
923 @node Sending a patch from a git repo, Vanilla sources (no repo), Patches, Patches
924 @comment node-name, next, previous, up
925 @chapter Sending a patch from a git repo
927 @cindex contributions
931 Firstly, if you can set up an accessible remote repo, please do so.
932 You can see how easy it is in section @xref{Setting up a publicly
933 accessible repo}. It will make things so much easier for everyone.
934 We do understand that there may be some valid reasons why you can't,
935 and that is okay, this section still provides a valid workflow.
937 Before you do anything, we recommend that you run the
938 @code{git-for-steve.sh} script which you'll find in the @code{contrib}
939 directory. It will ensure that some basic git config settings are
940 correct, and set up your ``for-steve'' tracking branch.
942 @subheading Preparing a patch from a git repo
944 Are you in the right place? You cloned the SXEmacs sources with
945 @code{git clone http://git.sxemacs.org/sxemacs}.
947 Yes? OK, great, read on.
949 Your workflow should run something along these lines@dots{}
953 @code{git pull} from your ``for-steve'' branch to sync up with the main
956 @code{git checkout -b mybugfix} to create and checkout a new branch.
957 You can call it whatever you like, just as long as @emph{you} know
958 what it's about. (Yeah, we recommend that you do all your work on
959 branches and keep your master branch as pristine as possible).
961 hack hack edit edit fix fix hack
963 Test! If all is good, proceed. If not, return to the previous step.
965 The next step is to commit your changes, and at this point I'd like to
966 note that, although not mandatory, we encourage and prefer it if
967 you sign all of your commits with GnuPG. This can be easily set up
968 via @code{git config commit.gpgSign true}@footnote{Already done for
969 you if you ran the @code{git-for-steve.sh} script and it found your
972 Depending on how you like to deal with change logs, and if the changes
973 were small and trivial or detailed and large:
977 @code{git commit -sam "Summary of changes"} For use with small quick
978 changes that don't really warrant verbose logs to document them.
980 @code{git commit -sa} This form will fire up an editor for you to
981 write your change logs in@footnote{You can set which editor to use
982 with @code{git config --global core.editor my_fav_editor}. @s{} has
983 his set to a shell function called @dfn{edit} which fires up gnuclient
984 if SXEmacs is running, or SXEmacs if not.}.
986 @code{git commit -saF mylogfile} Use this form for the times when you
987 have logged your changes as you went to the file @file{mylogfile}.
990 Please take note, that whichever commit command you use, to
991 @emph{always} use the @code{-s} option to add a @dfn{Signed-off-by}
992 entry to the log. This will indicate that you played some role in
993 getting the patch into the code base, and, perhaps more importantly,
994 you had permission to do so@footnote{There might be
995 licencing/copyright things to be aware of, especially in the case of
996 working on SXEmacs either for your employer, or during your employer's
999 For patches that you're submitting to the main SXEmacs code base that
1000 have originated from somebody else (maybe you have a small team of
1001 sub-developers working for you), the @dfn{Signed-off-by} entry also
1002 indicates that you have reviewed, tested, and approved the patch. And
1003 also, the original author has permission to submit it.
1005 @code{git checkout for-steve} To flip back to your for-steve branch.
1007 @code{git merge mybugfix} To merge the changes from the
1008 @dfn{mybugfix} branch into your for-steve branch.
1010 At this point everything that was in the @dfn{mybugfix} branch is now
1011 in your for-steve branch, so you no longer need it. You can safely delete
1012 it with @code{git branch -d mybugfix}.
1014 Now if you have a publicly accessible repo, you should do:
1016 @code{git push myremote for-steve} To push the changes to your publicly
1017 accessible repo, @dfn{myremote}.
1020 If your repos is private, it is safe to skip the push and just advance
1023 @subheading Patch Submission
1025 @anchor{Patch Submission}
1026 At this point, your changes are ready for @s{} to incorporate into
1027 the main SXEmacs code base. All you need to do is let him know, and
1028 you can easily do that with the following 2 git commands@footnote{The
1029 @code{git-for-steve.sh} contrib script will set a lot of these for you.}:
1033 @code{git format-patch --add-header="X-Git-Repo: REPO-URL" \@*
1035 --add-header="X-Git-Branch: for-steve" \@*
1037 --subject-prefix="P-Req" --minimal --numbered -o DIR origin/master}
1039 @code{git send-email \@*
1041 --to="SXEmacs Patches <sxemacs-patches@@sxemacs.org>" \@*
1043 --from="$(git config user.name) <$(git config user.email)>" DIR}
1046 If you not have have a publicly accessible repository, the SXEmacs
1047 developers can't pull in your changesets directly from you. Instead,
1048 once your patch hits the mailing list and is approved, it will have to
1049 be applied manually to the SXEmacs code base.
1051 You could, in theory, use a post-commit hook, but I'd not recommend
1052 it. Think about the situation where you are working on something
1053 fairly big. You'd most likely commit several times before you have
1054 things ready for us.
1056 If you have a publicly accessible repo, be sure to setup automation
1057 like in @xref{Automation}.
1059 @node Vanilla sources (no repo),, Sending a patch from a git repo, Patches
1060 @comment node-name, next, previous, up
1061 @chapter Vanilla sources (no repo)
1063 @cindex contributions
1067 Are you in the right place? All you have is a SXEmacs source tarball
1068 and you don't have @file{git} installed.
1070 Yes? OK, great, read on.
1072 You will have the toughest time of it I'm afraid because you will have
1073 to do everything manually. But it isn't too bad. No worse than for any
1076 Your hacking cycle will look something like this:
1080 Unpack the source tarball somewhere and @emph{don't touch it}. This
1081 will be your pristine sources.
1083 Make a copy of your pristine sources somewhere else. This will be your
1084 working tree where you make your changes.
1086 cd into your working tree and hack hack hack
1088 Jump out of your working tree and do:
1089 @code{diff -urNp pristine-tree working-tree > my-sxemacs.diff}
1091 A note of caution here: Please ensure that you are diff'ing clean
1092 trees. In other words, run @code{make distclean} in your working tree
1093 @emph{before} creating the diff.
1095 Send @file{my-sxemacs.diff} (gzip'd if large) as a MIME attachment
1096 together with a detailed description of your changes to the
1097 @email{sxemacs-patches@@sxemacs.org, SXEmacs Patches} mailing list.
1100 @node Feature Requests, Support Requests, Patches, Top
1101 @comment node-name, next, previous, up
1102 @chapter Feature Requests
1103 @cindex request, feature
1105 From time to time someone will wander into the mailing list or our
1106 IRC channel saying something like "ya know, SXEmacs is cool, but it
1107 would truly @emph{rock} if it had @dfn{fooble-klangers}. How 'bout
1108 it guys? Can somebody please add @dfn{fooble-klangers} to SXEmacs?".
1110 @emph{That's} a @dfn{Feature Request}.
1112 It doesn't matter what a @dfn{fooble-klanger} is. It doesn't matter
1113 if having said @dfn{fooble-klanger} would make SXEmacs rock or not.
1114 What @strong{DOES MATTER} is that we acknowledge the request. And we
1115 acknowledge it quickly.
1117 So how quick is quickly? Anything greater than 48 hours is @emph{slow}.
1118 We should try to get an initial ack out within 24 hours of the feature
1119 request hitting the mailing list@footnote{All legitimate feature requests
1120 should eventually end up on the @uref{http://issues.sxemacs.org/, SXEmacs
1121 Issue Tracker}.}. I totally understand that the 24 hour turn-around
1122 won't always be possible. Often there'll be extenuating circumstances
1123 (I'm writing this right now in the middle of a 2 week period with no
1124 internet connection).
1126 The acknowledgment doesn't need to be anything more than just that, an
1127 acknowledgment. You don't need to have a 100,000 lines of working
1128 code that proves how much @dfn{fooble-klangers} make or don't make
1129 SXEmacs rock before you let the guy know that he isn't talking to a
1132 A feature request can only end up in one of 3 scenarios...
1143 Of those, #3 is @strong{UNACCEPTABLE}! That means, if you see a
1144 feature request that is more than 48 hours old and hasn't been
1145 acknowledged, it is @strong{YOUR} responsibility to do something about
1148 A feature request on our @uref{http://issues.sxemacs.org/, Issue
1149 Tracker} is a issue that has the @dfn{FeatReq} flag set and the
1150 severity set to @dfn{enhancement}.
1153 @node Support Requests, Bug Reports, Feature Requests, Top
1154 @comment node-name, next, previous, up
1155 @chapter Support Requests
1156 @cindex request, support
1158 Support requests are a call for help from our users and as such have
1159 @emph{top priority}. Much of @xref{Feature Requests}, applies equally
1162 Support requests are @emph{everyone's} responsibility, so if you see
1163 one and you think you can help, do so.
1165 @node Bug Reports, Making Releases, Support Requests, Top
1166 @comment node-name, next, previous, up
1167 @chapter Bug Reports
1170 Bug reports are a @emph{good} thing. They show that people are using
1171 the code that you spent so much time and effort in writing. Bug
1172 reports are an opportunity to improve SXEmacs. Never be scared of bug
1173 reports. Never get annoyed or upset by bug reports. Welcome them.
1174 As a matter of fact, worry if you don't see any bug reports. That
1175 would mean we aren't working hard enough. :-)
1177 All bug reports have to be submitted to our
1178 @uref{http://issues.sxemacs.org/, Issue Tracker}. So it goes without
1179 saying that you already have an account on our Issue Tracker, and if
1180 you don't, go get one @emph{now}.
1182 Because the Issue Tracker is just that, it @dfn{tracks} issues, all
1183 followups and correspondence concerning a bug @emph{must} be added via
1184 the issue tracker itself. @emph{DO NOT} follow up to a bug report on
1185 the mailing list. If a bug report is submitted to the mailing list
1186 initially (because the submitter wasn't aware of our Issue Tracker),
1187 the person submitting the report should be directed to our
1188 @uref{http://issues.sxemacs.org/, Issue Tracker}. If they are
1189 unwilling or unable to do so, one of us will do so.
1191 If a bug report results in a patch and merge request, the summary of
1192 the patch log should contain the text: "(Closes bug #n)", where `n' is
1193 the number that our Issue Tracker has assigned to that bug. The bug
1194 should be marked as "fixed" (stating in which revision) on the Issue
1195 Tracker. It should not be marked "Closed" until just prior to a
1196 release. Closing bugs is the job and responsibility of the project
1197 lead, or whoever is responsible for making releases.
1200 @node Making Releases, New Features, Bug Reports, Top
1201 @comment node-name, next, previous, up
1202 @chapter Making Releases
1205 From time to time, at the project lead's discretion, a release
1206 will be made and tarballs created and made available on
1207 @uref{http://downloads.sxemacs.org/releases/, the SXEmacs download site}.
1209 The decision as to @emph{when} to cut a release is generally
1210 influenced by two factors:
1214 How stable the code base is currently.
1216 Whether the changes since the last release warrant a new release.
1219 The minimum number of revisions between releases is one. The maximum
1220 number of revisions between releases is, well, there is no maximum.
1222 The actual steps involved in cutting a release are:
1226 Finalise things like...
1229 Update @file{etc/NEWS}
1231 To get the numbers for the "Developer Stats" section, first get a list
1232 of unique committers for this release with@dots{}
1234 @code{git log --format=full v@cver{}..|grep Author|sort -u}
1236 And then for the number of actual commits for each developer do@dots{}
1238 @code{git log --oneline --no-merges --author=NAME v@cver{}..|wc -l}
1241 Make sure @file{INSTALL}, @file{PROBLEMS} etc are up to date.
1243 Update @file{sxemacs.texi} at@dots{}
1249 Update the codename and version in @file{autogen.sh}
1251 Update the versioning macros in this document.
1254 Commit those updates.
1256 @code{git commit -sam "SXEmacs v@nver{} is released!"}
1258 Create a new tag which will be the version number of this release.
1260 @code{git tag -s v@nver{} -m "SXEmacs v@nver{}"}
1262 Push it to the public repo.
1264 @code{git push --tags origin master}
1268 (in the release working directory)
1271 git archive --format=tar \
1272 --prefix=sxemacs-@nver{}/ HEAD | \
1273 (cd ~/upload && tar xf -)
1277 Clean out the working directory and do autotool preparations.
1280 HAMMER=1 ./autogen.sh
1284 Copy the autotool files to the exported tree
1287 cp -va libltdl ~/upload/sxemacs-@nver{} &&
1288 for f in $(git ls-files --others -i --exclude-standard); do
1289 cp -va $@{f@} ~/upload/sxemacs-@nver{}/$@{f@}
1297 git log --stat v@cver{}..v@nver{} > ~/upload/sxemacs-@nver{}/ChangeLog
1300 Create a diff against the previous version.
1303 git diff v@cver{}..v@nver{} > ~/upload/sxemacs-@cver{}-@nver{}.diff
1307 Create the tarballs, md5sums, and sigs:
1311 for compressor in bzip2 gzip lzma xz; do
1312 $@{compressor@} --keep sxemacs-@cver{}-@nver{}.diff
1314 for type in bz2 gz lzma xz; do
1315 tar --create --owner=0 --group=0 --auto-compress --file \
1316 sxemacs-@nver{}.tar.$@{type@} sxemacs-@nver{}
1317 md5sum sxemacs-@nver{}.tar.$@{type@} > \
1318 sxemacs-@nver{}.tar.$@{type@}.md5
1319 md5sum sxemacs-@cver{}-@nver{}.diff.$@{type@} > \
1320 sxemacs-@cver{}-@nver{}.diff.$@{type@}.md5
1321 gpg --detach-sign --armor --output \
1322 sxemacs-@nver{}.tar.$@{type@}.asc sxemacs-@nver{}.tar.$@{type@}
1323 gpg --detach-sign --armor --output \
1324 sxemacs-@cver{}-@nver{}.diff.$@{type@}.asc \
1325 sxemacs-@cver{}-@nver{}.diff.$@{type@}
1329 Move the tarballs, diffs, GnuPG sigs, and md5sums to
1330 @uref{http://downloads.sxemacs.org/releases/, SXEmacs Download Site}.
1333 for file in *.@{bz2,gz,lzma,xz,md5,asc@}; do
1334 scp $@{file@} downloads.sxemacs.org:downloads.sxemacs.org/releases
1339 Rename the @file{LATEST-IS-VER} file.
1341 ssh downloads.sxemacs.org \
1342 mv downloads.sxemacs.org/releases/LATEST-IS-@{@cver{},@nver{}@}
1346 Update www.sxemacs.org:
1350 Update @file{download.html}
1352 Add @file{ChangeLog-@nver{}} to the website
1354 Update @file{index.html}
1358 Send a release announcement to @email{sxemacs-devel@@sxemacs.org,
1359 SXEmacs Devel} and comp.emacs.xemacs.
1362 Commit the first patch to the next version, which would be adding a
1363 @file{ChangeLog.d/ChangeLog-@nver}
1367 @node New Features, Compatibility, Making Releases, Top
1368 @comment node-name, next, previous, up
1369 @chapter New Features
1370 @cindex feature, new
1372 How do you get a new feature into SXEmacs? It's not hard, but
1373 remember this, we look at any new feature in this order of
1378 Tested working code.
1380 A plan of action with @dfn{Proof of concept} code.
1382 A plan of action with a willingness to write the code.
1384 An idea with a willingness to move it to a real plan and then to
1387 An idea with a willingness to help test any code resulting from it.
1389 ``Hey, wouldn't it be cool if...''
1392 Don't be disheartened if you aren't a master programmer, quite often
1393 the best new features and ideas come from non-programmers. All too
1394 often the people writing the code get caught up in what they are doing
1395 and find it hard to see things from @dfn{outside of the box}. Anyone
1396 can help with ideas and with testing new code and features.
1398 Any new feature begins with an idea, and at @emph{that} point somebody
1399 should post that idea to @email{sxemacs-devel@@sxemacs.org, SXEmacs
1402 @node Compatibility, Copyright and Licencing, New Features, Top
1403 @comment node-name, next, previous, up
1404 @chapter Compatibility
1405 @cindex compatibility, xemacs
1406 @cindex compatibility, emacs
1408 All I'll say about this is that for the foreseeable future, SXEmacs
1409 will remain 100% backwardly compatible with XEmacs where emacs lisp is
1410 concerned. An emacs lisp package or library that runs on XEmacs
1411 @emph{will} run on SXEmacs.
1413 If you find a place where this isn't true, you should report it as a
1414 bug, @xref{Bug Reports}.
1416 If you find areas where SXEmacs is incompatible with GNU/Emacs at the
1417 emacs lisp level, that is an issue between GNU/Emacs and XEmacs. That
1418 doesn't mean that we won't ever port GNU/Emacs things to SXEmacs,
1419 we'll just do it in a way that doesn't break compatibility with XEmacs.
1421 @node Copyright and Licencing, Developer Recruitment, Compatibility, Top
1422 @comment node-name, next, previous, up
1423 @chapter Copyright and Licencing
1425 SXEmacs is an @dfn{Open Source} project. Because of that we can only
1426 accept code and contributions that are covered by an Open Source
1429 We differ from the GNU/Emacs project in that we will accept any
1430 @dfn{OSI} approved Open Source licence, not just the GNU GPL. That
1431 means that if you are more comfortable with, say, the BSD licence,
1434 We also won't ask you to reassign your copyright to anyone else. If
1435 you want to reassign your copyright to the FSF (for example), you can,
1436 but we won't reject any contributions from you because you haven't.
1437 @footnote{If you contribute code to SXEmacs that you want included in
1438 GNU/Emacs you will have to reassign copyright to the FSF. Please
1439 understand that that is a GNU/Emacs requirement and @emph{not} a
1440 SXEmacs requirement}
1442 @subheading SXEmacs and your Employer
1443 This is @strong{very} important. If you write code for SXEmacs either
1444 on your employer's time (while you are at work), or using your
1445 employer's resources (hardware, software, electricity, furniture, etc)
1446 then your employer may have legal copyright of your work.
1448 @strong{PLEASE} be up front with your employer and clear it with them
1449 @strong{before} you write anything for SXEmacs. It is OK and
1450 perfectly acceptable to submit contributions to SXEmacs that are
1451 copyrighted to your employer, providing (and this is the key) your
1452 employer is willing to release the code under an approved OSI
1455 Don't overlook or dismiss this. It is here to safeguard you, your
1456 employer, the SXEmacs project as a whole, and @sy{} personally.
1458 @subheading Documentation Licences
1459 Please don't licence any documentation under the FSF's new @dfn{Free
1460 Documentation Licence}. This isn't a slight against the FSF or the
1461 GNU project, it is just because it will mean that our documentation
1462 would not be able to be included in XEmacs. It may even cause
1463 problems going the other way as well (XEmacs to SXEmacs).
1465 For that reason, we'll err on the side of caution.
1467 @node Developer Recruitment, Making/Altering Policies, Copyright and Licencing, Top
1468 @comment node-name, next, previous, up
1469 @chapter Developer Recruitment
1472 We don't actively try to recruit new developers in any kind of formal
1473 way. What we do is use SXEmacs for everything everyday and not hide
1474 the fact that we do. :-) That in itself makes people curious and some
1475 ask about this thing called @dfn{SXEmacs}. Show them what it is,
1476 point them to the @uref{http://www.sxemacs.org/, web site}, encourage
1477 them to subscribe to @email{sxemacs-devel@@sxemacs.org, SXEmacs
1478 Devel}, and even help them get an account on
1479 @uref{http://issues.sxemacs.org/, Our Issue Tracker}. And low and
1480 behold! We have a new developer.
1482 One recruitment tool that we do have is @dfn{sxemacs.org} email
1483 addresses. If you'd like one, contact @sye{}. Then you can use that
1484 email address whenever and whereever you like. Hmm, perhaps not
1485 @emph{everywhere}, it might not look so good if you use it for log in
1486 details to a pr0n site. :-P
1488 @node Making/Altering Policies, Version Control, Developer Recruitment, Top
1489 @comment node-name, next, previous, up
1490 @chapter Making/Altering Policies
1491 @cindex policies, changing
1493 How do you get these policies and proceedures changed? Simple. Just
1494 post to @email{sxemacs-devel@@sxemacs.org, SXEmacs Devel} stating
1495 where what how when and why. If it is non-controversial and makes
1496 sense, it'll probably be accepted quickly. If not, there could be
1497 lengthy @dfn{discussions} and possibly even a vote @xref{Voting}.
1499 @sy{} will always have the final word and make the ultimate decision,
1500 but he isn't an immovable force, his mind can be changed and he
1501 @emph{does} listen to what the rest of the project is saying. :-)
1503 @node Version Control, Concept Index, Making/Altering Policies, Top
1504 @comment node-name, next, previous, up
1505 @chapter Version Control
1506 @cindex version control
1511 The SXEmacs Project keeps control of its sources with git, starting
1512 with version 22.1.13.
1513 The main repository is that of the Project Lead (@sy{}). It is
1517 http://git.sxemacs.org/sxemacs
1520 Checking out a copy of SXEmacs is as easy as:
1523 git clone http://git.sxemacs.org/sxemacs
1526 The chapter on patches @pxref{Patches} will show you how to prepare
1527 and send in your contributions.
1530 * Setting up a publicly accessible repo::
1531 A git repo that others have read
1533 * Setting up a private repos:: A git repo only you have access to.
1534 * Other Developers' Repositories:: Git repos of regular developers of
1539 @node Setting up a publicly accessible repo, Setting up a private repos, Version Control, Version Control
1540 @comment node-name, next, previous, up
1541 @chapter Setting up a publicly accessible repo
1542 @cindex version control
1545 @cindex contributions
1547 You only need to read this section if you are able to host a publicly
1548 accessible repo somewhere.
1550 Getting everything set up is really very easy. I think you'll be
1551 quite surprised if you haven't done this sort of thing before. In the
1552 examples below I'm assuming that you have shell access to your remote
1556 user@@localhost ~ $ ssh user@@your.host
1557 user@@host ~ $ mkdir -v sxemacs
1558 user@@host ~ $ cd !$
1559 user@@host ~/sxemacs $ git init --bare
1560 user@@host ~/sxemacs $ echo @dfn{Your Name's SXEmacs Repo} > description
1561 user@@host ~/sxemacs $ exit
1562 user@@localhost ~ $ git clone http://git.sxemacs.org/sxemacs
1563 user@@localhost ~ $ cd sxemacs
1564 user@@localhost ~/sxemacs $ contrib/git-for-steve.sh
1567 And that's it! Told you it was easy, didn't I? All you have to do
1568 now is push your local copy to your remote@dots{}
1571 git push @var{myremote} master
1578 The last two commands for patch submission listed in @xref{Patch
1579 Submission}, @code{format-patch} and @code{send-email} are fairly long
1580 and hairy. You'd no doubt have trouble remembering them. But, never
1581 fear, git has a few tricks up her sleeve to make your life easier.
1583 @subsection Automating with Hooks
1585 If you are lucky enough to @emph{NOT} be using github@footnote{github
1586 is great and may be the ideal solution for you to host your repo
1587 somewhere, but it is inflexible in that you get no shell access, you
1588 can't set up custom hooks, and you are very limited in what git config
1589 settings you can tweak.} to host your publicly accessible repo you can
1590 set up a @dfn{post-receive} hook to automatically send your pull
1591 requests to the SXEmacs mailing list when you push to it.
1593 @subsection Setting Up The post-receive Hook
1595 Remember: This hook runs from your publicly accessible repo (your
1596 remote), and @emph{NOT} from your local working directory. It is
1597 called after you push to your remote.
1599 Jump over to your remote now and follow these steps
1603 Take a look in the file
1604 @file{hooks/post-receive.sample}. At the bottom of that file there is
1605 a commented line, that when uncommented would call another script,
1606 @file{post-receive-email}. Check that the path is correct, and
1609 Rename @file{hooks/post-receive.sample} to @file{hooks/post-receive}
1611 Tweak the remote's config with@dots{}
1614 git config hooks.mailinglist \
1615 "SXEmacs Patches <sxemacs-patches@@sxemacs.org>"
1616 git config hooks.envelopesender "Your Name <your@@email>"
1617 git config hooks.emailprefix "[P-Req] "
1618 git config hooks.showrev "git show -C %s; echo"
1621 @code{echo "Your Name's SXEmacs Repo" > description}
1624 Take note that the SXEmacs mailing lists will funnel any post from
1625 non-subscribers into the moderation queue. So make sure that the
1626 address you set @dfn{hooks.envelopesender} to is subscribed to the
1629 Also be aware that using this @dfn{post-receive} hook will mean that
1630 every time you push to your publicly accessible repo, a message will be
1631 sent to sxemacs-patches; this includes instances where you merely
1632 are pulling the latest from mainline and mirroring. Hence, the use of
1633 aliases as discussed below may be preferable. We are looking into
1634 ways of avoiding this sort of annoyance.
1636 @subsection Automating with Aliases
1638 @anchor{Automating with Aliases}
1639 Git allows you to define aliases that will let you do all kinds of
1640 funky things. Remember those hairy @code{format-patch} and
1641 @code{send-email} commands?
1644 git config alias.sxe-fp 'format-patch --add-header="X-Git-Repo: REPO-URL" \
1645 --subject-prefix="P-Req" --numbered'
1647 git config alias.sxe-sm 'send-email \
1648 --to="SXEmacs Patches <sxemacs-patches@@sxemacs.org>" \
1649 --from="$(git config user.name) <$(git config user.email)>"'
1652 With those 2 aliases set you can get your pull requests in by
1655 @code{git sxe-fp -o DIR origin && git sxe-sm DIR}
1657 @subsection Making Life Even Easier with git config
1659 You can make your life even easier by having git store things in its
1660 config. In this case, you can store those @code{format-patch} and
1661 @code{send-email} command line options in the repo's config@dots{}
1664 git config format.headers "X-Git-Repo: YOUR-REMOTE-URL"
1665 git config format.subjectprefix "P-Req"
1666 git config format.numbered true
1668 git config sendemail.to \
1669 "SXEmacs Patches <sxemacs-patches@@sxemacs.org>"
1670 git config sendemail.from "Your Name <your@@email>"
1673 With those settings, the commands: @code{git format-patch -o DIR
1674 origin}, and @code{git send-email DIR} are now equivalent of the
1675 original long hairy ones mentioned further up.
1677 Be careful when setting up aliases and config settings that you only
1678 make them global if you absolutely have to. All the ones I've shown
1679 here have been repo-specific.
1681 The @file{git-for-steve.sh} script in our @file{contrib} directory is
1682 an easy (and recommended) way to set up your git repo. It'll make
1683 sure that you have everything set up correctly and in an optimal way.
1685 @node Setting up a private repos, Other Developers' Repositories, Setting up a publicly accessible repo, Version Control
1686 @comment node-name, next, previous, up
1687 @chapter Setting up a private repos
1688 @cindex version control
1691 @cindex contributions
1693 Git makes it as easy to create a private repo as getting a checkout
1694 of the source code. In fact, that is all you have to do.
1697 git clone http://git.sxemacs.org/sxemacs
1700 You may want to follow some of the steps in @xref{Automating with
1701 Aliases}, to ease your life when sending patches if you plan to
1702 contribute frequently from this repo. Please note that in this case
1703 you should not reference any REPO-URL.
1705 However if you do plan to contribute frequently, we strongly suggest
1706 you configure a publicly accessible repos.
1708 More details at @xref{Setting up a publicly accessible repo}.
1710 @node Other Developers' Repositories,, Setting up a private repos, Version Control
1711 @comment node-name, next, previous, up
1712 @chapter Other Developers' Repositories
1713 @cindex version control
1716 @cindex contributions
1718 As previously mentioned, the master SXEmacs repo is at:
1720 http://git.sxemacs.org/sxemacs
1723 Some of these repos may not be publicly accessible or may not be
1729 http://git.nelsonferreira.com/sxemacs
1732 http://midcom.steveyoungs.com/oss-vc/sxemacs.git
1735 git://github.com/zevlg/SXEmacs.git
1738 git://github.com/rudimeier/sxemacs.git
1741 http://bitbucket.org/kehoea/sxemacs/
1744 git://github.com/hroptatyr/sxemacs.git
1747 And of course the main repo (Steve's) is at:
1749 http://git.sxemacs.org/sxemacs
1750 http://git.sxemacs.org/website (our website is under git too)
1752 @subheading The tla repository for versions upto 22.1.12
1754 The old tla repos at http://arch.sxemacs.org/2010 still exist, and
1755 will remain forever. If you ever need anything from them just install
1756 @code{tla} and leech them with that.
1758 The reason we are keeping them around indefinitely is because the move
1759 to git meant a loss of history. There are tools available for
1760 converting a arch repo to git, but they failed to work in our case
1761 because of the cached revisions in our repos.
1763 @node Concept Index,, Version Control, Top
1764 @unnumbered Concept Index