org-maintenance.org

   1 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
   2 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   3 #+TAGS:       Write(w) Update(u) Fix(f) Check(c)
   4 #+TITLE:      Org maintenance
   5 #+EMAIL:      bzg at gnu dot org
   6 #+LANGUAGE:   en
   7 #+PRIORITIES: A C B
   8 #+OPTIONS:    H:3 num:nil toc:nil \n:nil ::t |:t ^:t -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc ':t
   9
  10 This document describes the tasks the Org-mode maintainers have to do
  11 and how they are performed.
  12
  13 * Git workflow
  14
  15 The git repository has two branches:
  16
  17 - master :: for current development.
  18
  19 - maint :: for bug fixes against latest major or minor release.
  20
  21 Bug fixes always go on =maint= then are merged on =master=.
  22
  23 New features always go on =master=.
  24
  25 * Releasing
  26
  27 ** Major release
  28
  29 The release number for main releases look like this: =9.1=
  30
  31 Main releases are made whenever Org is in a state where the feature
  32 set is consistent and we feel that the features that are implemented
  33 is something we want to support in the future.
  34
  35 A major release turns the current state of the master branch into a
  36 release.
  37
  38 When doing a /major release/, make sure all changes from the maint
  39 branch are merged into the the master branch, then merge the master
  40 branch back into maint to synchronize the two.
  41
  42 ** Minor release
  43
  44 The release number for minor releases look like this: =9.1.7=
  45
  46 Minor releases are small amends to main releases.  Usually they fix
  47 critical bugs discovered in a main release.  Minor bugs are usually
  48 not fixed -- they will be addressed in the next main release.
  49
  50 Only the fix to the bug is bundled into a release, without the main
  51 development work going on in the master branch.  Since the bug fix
  52 will also be needed in the master branch, usually the fix is made in
  53 maint then merged in master.
  54
  55 ** Tagging the release
  56
  57 When doing a major and a minor release, after all necessary merging is
  58 done, tag the _maint_ branch for the release with:
  59
  60   : git tag -a release_9.1.7 -m "Adding release tag"
  61
  62 and push tags with
  63
  64   : git push --tags
  65
  66 We also encourage you to sign release tags like this:
  67
  68   : git tag -s release_9.1.7 -m "Adding release tag"
  69
  70 ** Uploading the release files from the orgmode.org server
  71
  72 Log on the orgmode.org server as the emacs user and ~cd~ to ~~/git/org-mode~.
  73
  74 From there do
  75
  76   : make release
  77   : make upload
  78
  79 to create the =.tar.gz= and =.zip= files, the documentation, and to
  80 upload everything at the right place.
  81
  82 * Available Org's builds on the server
  83
  84 There are two cron tasks on the server: one that builds the ELPA
  85 packages and one that builds =org-latest.tar.gz= and =org-latest.zip=.
  86
  87 ELPA packages are built from the *maint* branch.  One ELPA package
  88 contains Org's core, another one called "org-plus-contrib" contains
  89 Org and contributed libraries.
  90
  91 =org-latest*= snapshots are built from the *master* branch.
  92
  93 * Synchronization Org and upstream Emacs
  94
  95 Below it is described how Org is kept in sync with the upstream Emacs.
  96
  97 ** Backporting changes from upstream Emacs
  98
  99 Sometimes Emacs maintainers make changes to Org files.  The process of
 100 propagating the changes back to the Org repository is called
 101 /backporting/ for historical reasons.
 102
 103 To find changes that need to be backported from the Emacs repository,
 104 the following =git= command, courtesy of [[http://permalink.gmane.org/gmane.emacs.devel/215861][Kyle Meyer]], can be used:
 105
 106 #+begin_src shell
 107 git log $rev..origin/emacs-25 -- lisp/org doc/misc/org.texi \
 108   etc/refcards/orgcard.tex etc/ORG-NEWS etc/org \
 109   etc/schema/od-manifest-schema-v1.2-os.rnc \
 110   etc/schema/od-schema-v1.2-os.rnc
 111 #+end_src
 112
 113 here, =$rev= is the last commit from the =emacs-25= branch that was
 114 backported.  The should also be done for the =master= branch.
 115
 116 There is also a [[http://git.savannah.gnu.org/cgit/emacs.git/atom/lisp/org/][feed]] to keep track of new changes in the =lisp/org=
 117 folder in the Emacs repository.
 118
 119 ** Updating the Org version in upstream Emacs
 120
 121 New releases of Org should be added to the [[https://git.savannah.gnu.org/cgit/emacs.git][Emacs repository]].
 122
 123 Typically, Org can be synchronized by copying over files from the
 124 =emacs-sync= branch of the Org repository to the =master= branch of
 125 Emacs repository.  The =emacs-sync= branch has a few extra changes
 126 compared with the =maint= branch.  If the Emacs maintainers are
 127 planning a new release of Emacs soon, it is possible that another
 128 branch should be used.
 129
 130 If the new release of Org contains many changes, it may be useful to
 131 use a separate branch before merging, e.g. =scratch/org-mode-merge=.
 132 This branch can then be merged with the =master= branch, when
 133 everything has been tested.
 134
 135 Please see [[http://git.savannah.gnu.org/cgit/emacs.git/tree/CONTRIBUTE][CONTRIBUTE]] in the Emacs repository for guidelines on
 136 contributing to the Emacs repository.
 137
 138 *** Where to files go
 139
 140 The following list shows where files in Org repository are copied to
 141 in the Emacs repository, folder by folder.
 142
 143 **** =org-mode/doc=
 144
 145 - =org.texi= :: Copy to =emacs/doc/misc=.  It may be necessary to replace,
 146      ~@include org-version.inc~ with ~@set VERSION 9.0.9~ or similar.
 147
 148 - =orgcard.tex= :: Copy to =emacs/etc/refcards=.  Make sure that
 149      ~\def\orgversionnumber~ and ~\def\versionyear~ are up to date.
 150
 151 **** =org-mode/etc=
 152
 153 - =styles/*= :: Copy to =emacs/etc/org=.
 154
 155 - =schema/*.rnc= :: Copy to =emacs/etc/schema=.
 156
 157 - =schema/schemas.xml= :: Any new entries in this file should be added
 158      to =emacs/etc/schema/schemas.xml=.
 159
 160 - =ORG-NEWS= :: Copy to =emacs/etc=
 161
 162 **** =org-mode/lisp=
 163
 164 - Copy =*.el= files to =emacs/lisp/org=, except =org-loaddefs.el=!
 165
 166 - You should create =org-version.el= in =emacs/lisp/org=.  The file is
 167   created when you =make= Org.
 168
 169 **** TODO =org-mode/testing=
 170
 171 *** Update  =emacs/etc/NEWS=
 172
 173 Whenever a new (major) version of Org is synchronized to the Emacs
 174 repository, it should be mentioned in the NEWS file.
 175
 176 * Updating the list of hooks/commands/options on Worg
 177
 178 Load the =mk/eldo.el= file then =M-x eldo-make-doc RET=.
 179
 180 This will produce an org file with the documentation.
 181
 182 Import this file into =worg/doc.org=, leaving the header untouched
 183 (except for the release number).
 184
 185 Then commit and push the change on the =worg.git= repository.
 186
 187 * Copyright assignments
 188
 189 The maintainers needs to keep track of copyright assignments.  Even
 190 better, find a volunteer to do this.
 191
 192 The assignment form is included in the repository as a file that you
 193 can send to contributors: =request-assign-future.txt=
 194
 195 The list of all contributors from who we have the papers is kept on
 196 [[https://orgmode.org/worg/org-contribute.html][this Worg page]], so that committers can check if a patch can go into
 197 the core.
 198
 199 The assignment process does not always go smoothly, and it has
 200 happened several times that it gets stuck or forgotten at the FSF.
 201 The contact at the FSF for this is: =copyright-clerk AT fsf DOT org=
 202
 203 Emails from the paper submitter have been ignored in the past, but an
 204 email from the maintainers of Org mode has usually fixed such cases
 205 within a few days.