Title: Introducing Sardana Enhancement Proposals (SEPs) SEP: 0 State: ACCEPTED Date: 2016-04-07 Drivers: Carlos Pascual-Izarra <cpascual@cells.es> URL: https://sourceforge.net/p/sardana/wiki/SEP0 License: http://www.jclark.com/xml/copying.txt Abstract: Workflow for managing discussions about improvements to Sardana and archiving their outcomes.
This is a proposal to organize discussions about Sardana enhancements,
reflect their current status and, in particular, to archive their
outcomes, via a new lightweight process based on Sardana Enhancement
Proposals (SEPs). This idea is a shameless copy of the Debian Enhancement Proposal
system with a few adjustments to the Sardana project reality.
The main reason for using SEPs is to provide a central index in which to list such
proposals, which would be useful to see at a glance what open fronts
there are at a given moment in Sardana, and who is taking care of them
and, additionally, to serve as a storage place for successfully
completed proposals, documenting the outcome of the discussion and the
details of the implementation.
A "Sardana enhancement" can be pretty much any change to Sardana,
technical or otherwise. Examples of situations when the SEP process
might be or might have been used include:
The workflow is very simple, and is intended to be quite lightweight:
an enhancement to Sardana is suggested, discussed, implemented, and
becomes accepted practice (or policy, if applicable), in the normal
Sardana way. As the discussion progresses, the enhancement is assigned
certain states, as explained below. During all the process, a single URL
maintained by the proposers can be used to check the status of the
proposal.
The result of all this is:
The actual discussions should happen in the sardana mailing lists (normally sardana-devel, unless the discussion may benefit from getting input from the wider audience of sardana-users). This way, SEPs do not act as yet another forum to be followed.
In the same way, SEPs do not give any extra powers or authority to
anyone: they rely on reaching consensus,
by engaging in discussions on mailing lists, IRC, or real life meetings
as appropriate. In case of dispute, the ultimate decision lies in the Sardana Executive Committee defined in the Sardana MoU.
The person or people who do the suggestion are the "drivers" of the
proposal and have the responsibility of writing the initial draft, and
of updating it during the discussions, see below.
A given SEP can be in one of the following states:
The ideal progression of states is DRAFT -> CANDIDATE -> ACCEPTED, but
reality requires a couple of other states and transitions as well.
In order for a SEP to become CANDIDATE, the following condition should
be met:
The CANDIDATE state is meant to prove, via a suitable implementation
and its testing, that a given SEP is feasible.
In order for a SEP to become ACCEPTED, the following condition should
be met:
Once accepted:
A SEP can become REJECTED in the following cases:
A SEP can become OBSOLETE when it is no longer relevant, for example:
In one of these states, no further actions are needed.
It is recommended that SEPs in one of these states carry a reason
describing why they have moved to such a state.
The only additional burden of the SEP process falls on the shoulders of its
drivers. They have to take care of all the practical work of writing
and maintaining the text, so that everyone else can just continue
discussing things as before. Driver's burden can be summarized as:
If the drivers go missing in action, other people may step in and
courteously take over the driving position.
Note: the drivers can of course participate in the discussion as
everybody else, but have no special authority to impose their ideas to
others. SEP gives pencils, not hammers.
A SEP is basically a free-form plain text file, except that it must
start with a paragraph of the following RFC822-style headers:
(Additionally, REJECTED SEPs can carry a "Reason:" field describing
why they were rejected.)
The rest of the file is free form. Since the SEP is kept in a wiki, using
its markup syntax is, of course, a good idea.
Suggested document contents:
The SEP must have a license that is DFSG free. You may choose the
license freely, but the "Expat" license is recommended. The
official URL for it is http://www.jclark.com/xml/copying.txt and
the license text is:
Copyright (c) <year> <your names> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
The justification for this recommendation is that this license is one
of the most permissive of the well-known licenses. By using this
license, it is easy to copy parts of the SEP to other places, such as
documentation for Sardana development or embedded in individual
packages.
The procedure to create a SEP is simple: send an e-mail to
sardana-devel@lists.sourceforge.net
, stating that you're taking the next
available number, and including the first paragraph of the SEP as
explained above. It is very important to include the list of drivers,
and the URL where the draft will be kept up to date. The next available
SEP number can be obtained by consulting
https://sourceforge.net/p/sardana/wiki/SEP.
It is also a very good idea to mention in this mail the place where the
discussion is going to take place, with a pointer to the thread in the
mailing list archives if it has already started.
The actual place where the SEP draft is going to be published is up to the SEP driver (e.g., it can be a plain text file or sphinx file in a code repository) but the sardana project provides infrastructure to host it in its wiki for convenience. If you decide to host the SEP draft in the sardana wiki, just create a new wiki page named https://sourceforge.net/p/sardana/wiki/SEPxxx, where xxx is the SEP number.
Independently of where the draft is hosted you should edit the list of SEPs in https://sourceforge.net/p/sardana/wiki/SEP to add a link to the new SEP.
If the feature, or whatever, of the SEP needs further changing later,
the process can start over with the accepted version of the SEP document
as the initial draft. The new draft will get a new SEP number. Once the
new SEP is accepted, the old one should move to OBSOLETE state.
As an exception, trivial changes may be done in the same SEP without
requiring a new SEP number as long as:
Note: A trivial change here is understood as a small modification that
does not alter the intention of the previous text and simply corrects
something that is clearly an unintended mistake (e.g., fixing a typo,
fixing a broken link, fixing a formatting mistake). Format translations (e.g.
adapting the Markdown formatting to reStructuredText format), can also be considered
trivial changes. In case of doubt or discrepancies, it is always better
to opt for the standard procedure of creating a new SEP that obsoletes
the current one.
The following copyright statement and license apply to SEP0 (this
document).
Copyright (c) 2013 Carlos Pascual-Izarra
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
2016-04-07:
cpascual Pass from CANDIDATE to ACCEPTED (it was in candidate for testing its application with several real cases, but its text has been basically unaltered since 2013)
2014-05-22:
cpascual Minor formatting changes
2013-12-09:
cpascual Added provision for Trivial Changes in "Revising an accepted SEP" section
2013-08-21:
cpascual Clarification of the procedure for creating a new SEP
2013-06-06:
cpascual Initial version written after crude "translation" of the DEP0