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