= !BluePrint: Releases =
[[TOC]]

== Introduction ==

Sahana Eden releases:
- ensure stability of core APIs, features and data models as basis for the implementation of custom solutions
- serve as reference points for user documentation
- serve as targets for issue resolution
- provide support tools for database migration
- provide migration pathways for backward-incompatible API changes

== Stable-Repository ==

Releases will be published in a dedicated "stable" repository on GitHub.

== Release Numbering ==

Release numbering will use a three-number schema like:

{{{
1.0.0 => Major.Minor.Update
}}}

=== Update ===

A change in the update number indicates a maintenance update of a release:

- releases critical fixes and enhancements (e.g. security issues, stability/performance issues, bugs)
- can contain enhancements, or feature previews
- can contain visual/UX improvements, but does not generally change feature behavior
- can add new ''optional'' dependencies
- is always API compatible (or backwards-compatible)
- does not require configuration updates
- does not require a database migration (web2py automatic migration sufficient)

* simple pull+automigrate sufficient
* upgrade can be fully automated/scripted
* no changes in custom templates required

=== Minor ===

A change in the minor release number indicates a new release in a release series:

- releases regular fixes and improvements, including new features
- is always API compatible (or backwards-compatible)
- can add new mandatory dependencies
- can require configuration updates
- can require scripted database migration

* upgrade can additionally require a configuration update and/or scripted database migration
* upgrade can be performed manually by sysadmins by following step-by-step instructions
* upgrade of custom templates could require minor interventions by template developer

=== Major ===

A change in the major release number indicates a new release series:

- releases major framework changes
- can break API backwards-compatibility and require adaption of custom template code and/or concepts
- can change or add dependencies, both optional and mandatory
- can require configuration updates
- can require database migrations, both scripted and manual

* upgrade will most likely require a manual database migration
* upgrade can be complex and will require solid experience with Sahana system administration
* upgrade of custom templates will require major interventions by template developer and/or professional support

== Requirements before Release ==

=== All Releases ===

- all critical issues, and issues targeting this release, are closed
- change log is complete
- all unit tests pass
- smoke tests pass for all standard templates for all demo accounts of the respective template (minimum admin@example.com and normaluser@example.com)
- template-specific selenium tests pass
- disputed trunk changes resolved

=== Minor or Major Number Release ===

- all API changes documented
- database migration scripts complete
- migration instructions complete
- user documentation updates ready for roll-out

== Requirements for Release ==

- Tagged commit in stable-repository (after non-selective pull from trunk)
- Change log published on GitHub releases
- Deployment tools can roll out dependencies
- Announcement on mailing list

== Release Cycle ==

- new release three months after the last release
- any time earlier if deemed necessary to roll out critical fixes, or appropriate to release enhancements or feature previews

----
BluePrint