Level 3 Package Proposal Template
Template version 1.1 (14 December 2008).
This page describes the outline that should be followed when writing proposals for SBML Level 3 packages. Proposals should be organized exactly as described here and include the information mentioned in the comments. (The green-colored comment text is informational only; the comments are not meant to be left literally in the final text of a proposal.)
The title should be concise yet descriptive, and focus on the functionality that the proposed package will add to SBML Level 3. Avoid titles that are too broad or vague.
List the principal authors of this version of the proposal. (Each past version of the proposal will have its own author list, so a given version should list the authors who were most responsible for the development and writing of that particular version.)
Proposal tracking number
This is the number assigned by the issue tracking system for SBML. Obtaining a tracking number is one of the steps described in the SBML development process for Level 3. There will be only one tracking number for all versions of the same proposal. The tracker will be used by the SBML Editors to record comments, questions, and other miscellaneous information about a proposal.
Version number and date of public release
Version X released on DD Month YYYY.
This is the version number and date of release of this version of the proposal. A version number and a date are crucial information, because proposals evolve and any discussions surrounding a proposal must be made in reference to a specific release of the proposal.
URL for this version of the proposal
This URL should point to the main copy of this version of the proposal. If the proposal is written as a wiki page on the SBML.org Community Wiki, then the URL should be the full path to the wiki page. If it is stored in an SVN repository (such as the SourceForge.net repository for the SBML project), this should be a link to a web-based SVN browser view of the directory containing the proposal files. This information may seem redundant, but it becomes important when copies of the proposal are printed or distributed in PDF or other format.
URL for the previous version of this proposal
If this is a new revision of a previous proposal, include a URL to a copy of the previous version. This makes it possible for readers to trace the development and changes in the proposal.
Introduction and motivation
This section should introduce, summarize, and motivate the proposal. Keep in mind that, human nature being what it is, most readers will only read the proposal up to this point. The more cogent the introduction is, the more likely that readers will understand and appreciate the need for the proposed package.
Problems with current SBML approaches
Describe and illustrate what is wrong with the way that one might represent the necessary information currently in SBML Level 3.
Past work on this problem or similar topics
Include here a discussion of any other relevant proposals and other documents that influenced the development of this proposal. Make the description a narrative that explains the progression of ideas, not just a list of pointers to other documents.
Proposed syntax and semantics
In this section, the technical core of the proposal should be presented in full detail. Data structures should be defined using UML notation, optionally with pieces of XML Schema, following the same approach described in the most recent versions of the SBML Level 2 specifications.
Any dependencies on other SBML Level 3 packages must be described in this section.
Use-cases and examples
This section should provide examples and concrete use cases for how the proposed package will operate in the context of the package's intended applications.
This section should note the availability of prototype implementations (if any) of the proposed package.
Translation to SBML Level 2
Many proposed packages for SBML Level 3 are syntactic enhancements. The equivalent model often can be represented in SBML Level 2, though perhaps with an increase in model size and complexity. Nevetheless, being able to translate models to Level 2 is an important advantage, both for testing and understanding the proposed package, and for the possibility that applications may be able to read such models even before the applications are updated to support Level 3. If the proposed package results in models that can still be mapped or "flattened" to SBML Level 2, use this section to describe how to do that. Provide an algorithm in pseudocode if possible.
In this section, note any known unresolved questions or other issues that should be brought to the attention of readers.
Appendices are optional; they may be used to provide additional information that may be useful for understanding both the proposed package and its context.