Change handling and stability keeping procedures - STEMLab/geotools GitHub Wiki

• Motivation: make trunk hacking more controlled

• Contact: Andrea Aime

• Tracker: https://osgeo-org.atlassian.net/browse/GEOT-1078

• Tagline: Keep trunk stabled like an elephant

This proposal working on trunk more controlled and managed:

• We want trunk to be be directly followed by projects such as Geoserver or uDig
• We want to strike a balance that allows evolution, but forbids controversial changes and situations that may lead into long term instability

This proposal contains rules that should make trunk hacking more controlled and more amenable to be directly followed by projects such as Geoserver or uDig.
Rules try to strike a balance that allows evolution, but forbids controversial changes and situations that may lead into long term instability of the trunk itself.

Significant change to the Geotools API must be subjected to the following procedure:

• change shall be described in a wiki page listing:

  • the need to be addressed
  • the solution design
  • wheter a deprecate/remove cycle is possible/needed (it's usually impossible from GeoAPI change, it's not needed for brand new API)
  • the impact on current API, as well as a migration guide that allows to evaluate the impact of changes on the code
  • Child of Proposals page
  • a few code examples of the new API would be appreciated too

• a jira issue pointing at the wiki page shall be created in a dedicated jira module. The issue will be used to:

  • discuss the proposal (everyone instersted in the change shall subscribe to the issue)
• • voting by PMC members

A public API change impacting multiple modules is considered to be significant, whilst a change localized in the public API of a single extension or plugin module won't be usually subjected to this process. Anyways, we trust change makers to use common sense and apply to the procedure every time they do feel it's necessary.

To avoid proposal stagnation by lack of intererst/time from other PMC member the following rules apply:

• svn access for changes is granted within 3 days from the proposal, unless any objection is raised in the jira issue;
• a proposal is accepted automatically within 15 days from the proposal unless objections are raised in the jira issue.

Objections shall be addressed and countdown be restarted. Of course, if the issue gets successfully voted by the PMC countdown does not apply.

If the change is successfully voted, every code example in trunk shall be modified to follow the new API. This is, again, responsibility of whoever proposed the change. Once code samples are modifed, the issue can be closed.

Trunk must be subject to a continuous build process with online tests enabled, in order to catch whichever breakage occurred as a result of hacking.

Since full builds can require significant time, a compromise can be to have two build servers, one working "continuously" with quick tests, and another one working with full build but configured to build not more often than every few hours, eventually just twice a day.

When the build is broken, the first priority or whoever broke it is to restore proper building: people hacking on trunk shall be concerned with their own work, not with trying to fix other people errors.

If a change is applied that extensive build break is foreseen, it shall be discussed and organised on the mailing list to PMC satisfaction before being undertaken.

This proposal has been approved by the PMC:

• +1 Chris Holmes
• +1 Ian Turton
• +1 Jody Garnett
• +1 Justin Deoliveira
• +1 Simone Giannecchini

Community Support:

• +1 Jesse Eichar

• Proposals

A target release is also provided for each milestone.

Milestone 1	2.4.M0	Full Continuous Build
✅	Justin Deoliveira	Ask for volunteer hardware
✅	Justin Deoliveira	Set up continuum for simple install
⚠️	Justin Deoliveira	Set up continuum to deploy to repository
❎		Update project procedures for continuum

Milestone 2	2.4.M0	Test Project Procedure
✅	Jody Garnett	Update developers guide, and tag procedure changes "pending"
✅	Jody Garnett	Create wiki template for new proposals
⚠️	Jody Garnett	Test procedure (and template) on a sample proposal
❎		Adjust process based on feedback

Milestone 3	2.4.0	Publish Project Procedure
	Andrea Aime	Review modified developers guide and remove "pending" tags
❎		Included modified developers guide in 2.4.0 release

This is a process change, no API will be harmed.

Website:

• Update wiki with a Proposals page and Template

Developers Guide:

• Create a developers guide procedure page: GeoTools change proposal
• Update (or remove): Working on the stable branch
• Provide a page on continuum care and feeding: Continuous Integration

Issue Tracker:

• Look into making a proposals component