Title: Introducing Taurus Enhancement Proposals (TEPs) TEP: 0 State: ACCEPTED Date: 2016-04-07 Drivers: Carlos Pascual-Izarra <cpascual@cells.es>, Tiago Coutinho <coutinho@esrf.fr> URL: https://sourceforge.net/p/tauruslib/wiki/TEP0 License: http://www.jclark.com/xml/copying.txt Abstract: Workflow for managing discussions about improvements to Taurus and archiving their outcomes.
This TEP is an adaptation of SEP0
This is a proposal to organize discussions about Taurus enhancements, reflect
their current status and, in particular, to archive their outcomes, via a new
lightweight process based on Taurus Enhancement Proposals (TEPs). This idea is
a copy of the Sardana Enhancement Proposal system which is itself a copy of the
Debian Enhancement Proposal system with a few adjustments to the Taurus project
reality.
The main reason for using TEPs 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 Taurus, 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 "Taurus enhancement" can be pretty much any change to Taurus, technical or
otherwise. Examples of situations when the TEP process might be or might have
been used include:
The workflow is very simple, and is intended to be quite lightweight: an
enhancement to Taurus is suggested, discussed, implemented, and becomes
accepted practice (or policy, if applicable), in the normal Taurus 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 taurus mailing lists (normally
taurus-devel, unless the discussion may benefit from getting input from the
wider audience of taurus-users). This way, TEPs do not act asyet another forum
to be followed.
In the same way, TEPs 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 Taurus Executive Committee defined in the Taurus 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 TEP 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 TEP 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 TEP is feasible.
In order for a TEP to become ACCEPTED, the following condition should
be met:
Once accepted:
A TEP can become REJECTED in the following cases:
A TEP 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 TEPs in one of these states carry a reason
describing why they have moved to such a state.
The only additional burden of the TEP 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. TEP gives pencils, not hammers.
A TEP is basically a free-form plain text file, except that it must
start with a paragraph of the following RFC822-style headers:
(Additionally, REJECTED TEPs can carry a "Reason:" field describing
why they were rejected.)
The rest of the file is free form. Since the TEP is kept in a wiki, using
its markup syntax is, of course, a good idea.
Suggested document contents:
The TEP 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 TEP to other places, such as
documentation for Taurus development or embedded in individual
packages.
The procedure to create a TEP is simple: send an e-mail to
taurus-devel@lists.sourceforge.net
, stating that you're taking the next
available number, and including the first paragraph of the TEP 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
TEP number can be obtained by consulting
https://sourceforge.net/p/tauruslib/wiki/TEP.
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 TEP draft is going to be published is up to the TEP
driver (e.g., it can be a plain text file or sphinx file in a code repository)
but the taurus project provides infrastructure to host it in its wiki for
convenience. If you decide to host the TEP draft in the taurus wiki, just
create a new wiki page named https://sourceforge.net/p/tauruslib/wiki/TEPxxx,
where xxx is the TEP number.
Independently of where the draft is hosted you should edit the list of TEPs in
https://sourceforge.net/p/tauruslib/wiki/TEP to add a link to the new TEP.
If the feature, or whatever, of the TEP needs further changing later,
the process can start over with the accepted version of the TEP document
as the initial draft. The new draft will get a new TEP number. Once the
new TEP is accepted, the old one should move to OBSOLETE state.
As an exception, trivial changes may be done in the same TEP without
requiring a new TEP 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 TEP that obsoletes
the current one.
The following copyright statement and license apply to TEP0 (this
document).
Copyright (c) 2014 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 contents have been basically unaltered since its creation)
2015-05-13:
cpascual Fixed date in header. Fixed state (it was outdated as DRAFT, when it should be CANDIDATE)
2014-01-27:
tiagocoutinho Change main author and copyright
2014-01-23:
tiagocoutinho Initial version written as a copy of SEP0
Wiki: [TEP0] 2016-11-16 17:02:34.926454#1
Wiki: [TEP0] 2016-11-16 17:02:34.926454#2