[SAC general-docs] draft XEmacs Developer's Guide

SUPERSEDES APPROVE COMMIT general-docs Argh, submitted mail from wrong saved patch. Try this one. Index: ChangeLog =================================================================== RCS file: /pack/xemacscvs/XEmacs/packages/xemacs-packages/general-docs/ChangeLog,v retrieving revision 1.20 diff -u -U0 -r1.20 ChangeLog --- ChangeLog 18 Feb 2007 16:17:27 -0000 1.20 +++ ChangeLog 12 May 2007 16:57:33 -0000 ＠＠ -0,0 +1,15 ＠＠ +2007-05-13 Stephen J. Turnbull <stephen(a)xemacs.org&gt; + + Publish xemacs-devguide. + + * Makefile (EXPLICIT_DOCS): Add xemacs-devguide.texi. + +2007-05-13 Stephen J. Turnbull <stephen(a)xemacs.org&gt; + + * texi/xemacs/xemacs-devguide.texi: + (Philosophy): Rewrite to look like XEmacs current practice. + (xemacs-review): New stub node for this mailing list. + (XEmacs Resources on the Internet): + (xemacs-winnt): + Fix links for new node. + ＠＠ -6,6 +20,0 ＠＠ - -2007-02-17 Stephen J. Turnbull <stephen(a)xemacs.org&gt; - - Publish XEmacs Developer's Guide. - - * Makefile (EXPLICIT_DOCS): Add xemacs-devguide.texi. Index: Makefile =================================================================== RCS file: /pack/xemacscvs/XEmacs/packages/xemacs-packages/general-docs/Makefile,v retrieving revision 1.13 diff -u -r1.13 Makefile --- Makefile 7 May 2005 12:23:54 -0000 1.13 +++ Makefile 12 May 2007 16:50:43 -0000 ＠＠ -27,6 +27,7 ＠＠ # We'll need something like this. #EXPLICIT_DOCS = texi/*.texi texi/xemacs/*.texi texi/packages/*.texi -EXPLICIT_DOCS = texi/xemacs/fontconfig.texi +EXPLICIT_DOCS = texi/xemacs/fontconfig.texi \ + texi/xemacs/xemacs-devguide.texi include ../../XEmacs.rules Index: texi/xemacs/xemacs-devguide.texi =================================================================== RCS file: /pack/xemacscvs/XEmacs/packages/xemacs-packages/general-docs/texi/xemacs/xemacs-devguide.texi,v retrieving revision 1.5 diff -u -r1.5 xemacs-devguide.texi --- texi/xemacs/xemacs-devguide.texi 18 Feb 2007 16:17:30 -0000 1.5 +++ texi/xemacs/xemacs-devguide.texi 12 May 2007 16:50:44 -0000 ＠＠ -1,10 +1,9 ＠＠ \input texinfo ＠c -*-texinfo-*- -＠c $Id: xemacs-devguide.texi,v 1.5 2007/02/18 16:17:30 stephent Exp $ +＠c $Id: xemacs-devguide.texi,v 1.1 2005/02/01 16:08:35 stephent Exp $ ＠c Generate HTML with: ＠c (shell-command "texi2html -number -monolithic xemacs-devguide.texi" nil) ＠c ＠c %**start of header -＠c This ＠setfilename tells makeinfo to DTRT for the *installed* .texi file. ＠setfilename ../../info/xemacs-devguide.info ＠settitle xemacs-devguide ＠c %**end of header ＠＠ -279,11 +278,10 ＠＠ ＠cindex Philosophy -＠strong{This node is hardly -changed from the ＠emph{MH-E Developers Guide}, and may not be -representative of the ＠value{PROJECT}. Sometimes stephen thinks much of -this would be a good statement of values, other times he doesn't. What -do you think? Submit a patch!} +＠strong{This node has a fair amount of content almost +unchanged from the ＠emph{MH-E Developers Guide}, and is not fully +representative of the ＠value{PROJECT}. However, everything here has +been espoused by XEmacs developers at one time or another.} This chapter discusses the philosophy and principles of the XEmacs project. The first section covers our coding philosophy, while the ＠＠ -296,41 +294,52 ＠＠ follows: ＠enumerate - ＠item -Keep the C code fast, and only then featureful. +Keep the C code fast. ＠item Refrain from adding lots of code to the C codebase that would be better served with Lisp. ＠item -XEmacs should be easy to use out-of-the-box for new users. +XEmacs is a cross-platform application. Features should work on all +platforms. +＠item +XEmacs should be easy to use out-of-the-box for new users. ＠end enumerate -That last priority struggles mightily with the other priorities. For -example, the user ＠i{could} write his own Lisp for many features. -However, the average user is not going to do so. - ＠cindex customize - We should get as much mileage out of ＠code{customize} as we can to reduce the amount of code that users have to write. -One other subject related to philosophy is to what constitutes a major -release. Major releases signal to the user that the new version may -not work as it did before and that reading of the release notes is -mandatory. Major releases occur when incompatible changes are made -that are visible to the user. Types of changes include changing the -name of or deleting functions, key bindings, and customization -variables. The converse is true; these sorts of changes should not be -applied to minor releases. - -By itself, merely adding a new feature does not just justify a major -release. On the other hand, a major release is called for if the code -is completely rewritten, even if the user cannot notice any -difference. +XEmacs at any time has a ＠emph{stable} branch and uses the ＠emph{trunk} +for development. We do not freeze the trunk, except for the short +period of time needed to create a consistent release branch. The +release branch in principle should only be changed for bug fixes. (In +the past this principle has been honored as much in the breach as in the +observance; nevertheless, it's a good starting point.) + +A change in the major version number indicates a pervasive change +affecting all users. For example, the introduction of Mule in version +20, the extensive user of the package system in 21, and Unicode support +in 22. A change in the minor version number reflects addition of +features, and accompanies an initial public release. A change in the +patchlevel reflects bugfix releases of the stable branch, while on the +trunk patchlevels are fairly arbitrary, reflecting regular beta +releases. + +The stable branch has a single gatekeeper, the listed maintainer. +Changes are made only by the maintainer, or at his convenience with +explicit authorization. Any XEmacs reviewer may make or authorize +changes to the trunk. Having commit privileges does ＠emph{not} +authorize changes; commit privileges are for the convenience of the +project and of regular contributors, but do not imply a direct say in +decisions. Conversely, we are always looking for new reviewers; the +review board is self-maintaining, but not closed. + +Individual packages, like the stable branch, may have a listed +maintainer. In those cases, the listed maintainer is the gatekeeper. ＠heading Guiding Principles ＠＠ -338,9 +347,8 ＠＠ ＠enumerate 1 ＠item -While we all are scratching an itch on this project, we also have very -few users and a great desire to have more. Our users are sacrosanct; -we will go the extra distance to please our users. +We all are scratching an itch on this project. We respect each others' +goals, which are quite varied. ＠item Using vulgar language towards our users and/or developers is ＠＠ -350,10 +358,8 ＠＠ The team makes decisions by consensus through articulated arguments. If one wants to express an opinion, they do it by presenting evidence to support their claim in a respectful way, and not by insulting -others' points of view. While it takes some time and effort to -articulate the reasons behind one's point of view, we enjoy the -process and often gain a better understanding of the issues by the -end. +others' points of view. Where consensus seems hard to achieve, what we +try first may be decided by a vote in the Review Board. ＠item We are all committed to a high-quality product. We have no artificial ＠＠ -397,9 +403,16 ＠＠ ＠end ifhtml ＠strong{Please ensure that the copyright notice of every file accurately -reflects your contribution, whether you have assigned your copyright or -not. This will aid future project admins greatly if there ever is a -merger.} +reflects your contribution, whether you have assigned your copyright to +the FSF or not. This will aid future project admins greatly if there +ever is a merger of XEmacs with Emacs.} ``Accurately reflects'' means +that if you have not assigned your contribution, ＠emph{your name} should +appear in a copyright notice, along with an accurate list of the years +in which your contributions were made. If you have assigned your +contribution, you should list the FSF (or other assignee) as copyright +holder, and make sure that the list of years is appropriately updated. +In both cases, an accurate ChangeLog detailing your changes (file and +function) should accompany the patch. You ＠strong{must} reference the GPL correctly in every file. ＠＠ -407,7 +420,10 ＠＠ they have various different licenses. ＠emph{Be careful}: it is typically ＠strong{not} permissible to mix excerpts from different documents with each other, or with XEmacs code, unless they have -＠emph{identical} licenses. +＠emph{identical} licenses. In particular, the XEmacs Texinfo manuals +(the ＠emph{XEmacs User's Guide}, the ＠emph{XEmacs Lisp Reference}, and +the ＠emph{XEmacs Internals Manual}) have a unique license which is not +the GPL or the GFDL, and is incompatible with both. All code and data files must be licensed under the GPL (or a compatible license) so that they can be added to XEmacs, and others may modify them. ＠＠ -515,8 +531,9 ＠＠ ＠item Reviewer A developer who may authorize developers, including himself, to write to the XEmacs CVS repository. ＠xref{XEmacs Reviewer}. Should participate -in ＠value{BETA-LIST} ＠ref{xemacs-beta} and ＠value{PATCHES-LIST} -＠ref{xemacs-patches}. +in ＠value{BETA-LIST} ＠ref{xemacs-beta}, ＠value{PATCHES-LIST} +＠ref{xemacs-patches}, and ＠value{REVIEW-LIST} +＠ref{xemacs-review}. ＠item XEmacs Review Board The reviewers as a group, responsible for delegating access to ＠＠ -526,13 +543,13 ＠＠ ＠xref{Jobs List}. ＠item Chairman of the Board -＠item CEO -＠item Maintainer -＠item Benevolent Dictator for Life +＠itemx CEO +＠itemx Maintainer +＠itemx Benevolent Dictator for Life Call it what you like, we don't have one any more, by deliberate choice. ＠item Meta-maintainer -＠item Mr. XEmacs +＠itemx Mr. XEmacs The reviewer responsible for trying to keep track of what isn't getting done, and finding someone to do it. The latter title allows him to tell his mother how important he is. More seriously, the meta-maintainer ＠＠ -541,8 +558,8 ＠＠ ＠value{BETA-LIST} ＠ref{xemacs-beta}. ＠item Release engineer -＠item Stable release engineer -＠item Package release engineer +＠itemx Stable release engineer +＠itemx Package release engineer Responsible for the quality control and adminstrative details of distributing some coherent package of functionality. The ＠dfn{stable release engineer} manages the core distribution, including the build ＠＠ -555,8 +572,8 ＠＠ ＠c #### Write nodes for these posts! ＠item Postmaster -＠item Webmaster -＠item CVS Manager +＠itemx Webmaster +＠itemx CVS Manager Administrators of the various Internet-based services important to XEmacs users and developers. ＠c #### Write nodes for these posts! ＠＠ -1930,7 +1947,7 ＠＠ ＠strong{The commit-trigger has not yet been implemented at the time of writing. For this reason -implicit self-approvals should still be avoided. (2007-02-17)} +implicit self-approvals should still be avoided. (2007-05-13)} ＠＠ -2177,6 +2194,7 ＠＠ * xemacs-patches:: * xemacs-mule:: * xemacs-winnt:: +* xemacs-review:: ＠end menu ＠＠ -2253,7 +2271,14 ＠＠ -＠node xemacs-winnt, , xemacs-mule, XEmacs Resources on the Internet +＠node xemacs-winnt, xemacs-review, xemacs-mule, XEmacs Resources on the Internet +＠section The xemacs-winnt Mailing List + +＠strong{Write me!} + + + +＠node xemacs-review, , xemacs-winnt, XEmacs Resources on the Internet ＠section The xemacs-winnt Mailing List ＠strong{Write me!} _______________________________________________ XEmacs-Patches mailing list XEmacs-Patches(a)xemacs.org http://calypso.tux.org/cgi-bin/mailman/listinfo/xemacs-patches