org-maintenance.org

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