Governance

SharedSDS project governance

SharedSDS governance must deliver long term stability and essential flexibility.

Open source licensing

The software is licensed under the GNU AGPL v3 or GNU LGPL v3 as required. Please get in touch to discuss your API requirements. 

Aim and Context

Initial development focus is the UN GHS "Purple Book" for substance and mixture classification.

Users will vote in the prioritisation (see diagram) process:

 

Development governance

 Governance overview Part 1

 

SharedSDS tickets

The ticketing infrastructure directly connects users with developers. Users create tickets for feature requests and defects. Proposed features and possible bugs are usually discussed in the user support mailing list before writing tickets.

Once a ticket nears the top of the prioritised backlog, work commences. Users discuss the requirements in detail with the assigned developer(s). The ticket author and other interested users participate in acceptance testing after the work is complete.

Decisions made about the work specified in a ticket are documented in comments appended to the ticket.

User documentation

If user documentation is required, a ticket should be raised specifying the precise documentation required.

If documentation exists and does not match the behaviour of the software it is a bug. A defect ticket should be raised to repair either the documentation or the software.

Generally, the user who specifies the enhancement should volunteer or recruit another user to interpret the spec and write the user documentation. If this can be done before work commences it greatly assists developers to deliver the ticketed feature(s).

Ticket triage

  • If a new ticket is virtually a duplicate of another, it will be immediately resolved as duplicate or if more appropriate it will replace the old ticket.
  • If a new ticket appears to be a misunderstanding, an appropriate comment should be added and the ticket resolved as invalid or wontfix
  • If the new ticket appears to report a defect and there is insufficient information to reproduce the bug it will be immediately resolved as either invalid or worksforme respectively.

Discussion in the users mailing list prior to submitting a ticket should minimise duplicate, invalid, wontfix or worksforme responses.

Defect tickets

  • If the ticket is a defect its default priority is normal. Other selectable priorities include trivial, minormajor or critical.
  • Defect priorities assigned by users may be changed or confirmed by the dev team after discussion with the users.
  • Both major and critical take precedence over routine feature development and are immediately assigned to an in-house Developer for action.
  • critical is applied as a release blocker or software rollback trigger.
  • The first step for anyone working on a defect is to write one or more tests which demonstrate the bug. The ticket number must be incorporated in each test method name.
  • When the work is done the ticket is submitted by the Developer to the Reporter of the defect for acceptance testing. The Reporter can either send it back to the Developer (needswork) or resolve it as fixed.
  • Anyone, may add themselves to the Stakeholders listed on the ticket to be included in all automatic notifications.
  • A ticket for a software defect might include among the acceptance tests: "Align documentation with repair"

Enhancement voting

  • If the ticket is for an enhancement, it enters the work backlog as new and stays there until voted up (or down) by users who agree it is a necessary enhancement
  • Voting motivation should always be based exclusively on "what's in it for me"
  • A good enhancement ticket starts with a clear and compelling title so it gains attention from other users
  • The ticket needs description (up to 50 words) which succinctly puts a compelling case for change so it attracts votes from other users
  • If the Foundation believes a proposed change is antithetical to its objectives it will argue the case against in mailing lists and ticket comments until the issue is resolved. 
  • Each year the Foundation annual conference formally reviews backlog items. Conference attendees and remotely attending Foundation Members are entitled to vote to settle the backlog priority for the coming year.

Ticket ownership

  • Before any in-house Developers are permitted to start work, ownership of the ticket must be "claimed" by someone who is prepared to accept or reject the finished work on behalf of all users.
  • An Owner can represent any number of users. The Foundation will provide mailing lists for such groups on request.
  • The ticket Owner must agree to answer Developer questions during the life of the ticket.
  • A ticket needs adequate (rather than detailed) specification before work starts
  • Specification is a joint task done by the Owner and a member of the dev team. The outcome is a set of acceptance tests which can prove the finished work.

Development

  • When a ticket is assigned for development the detailed specification done by the development team.
  • Development ceases as soon as the software passes all user acceptance tests
  • If the tests pass and Owner rejects the work, the ticket is sent back to the developer with a status of needswork.
  • Before further work is permitted specification changes must be reflected in adjusted acceptance tests
  • If there is significant adjustment of the ticket description, all the votes should be zeroed and the ticket returned to the backlog to restart its journey
  • If Owner accepts the work, the enhancement will be merged into the production version of the software ready for the next release.

Contributed repairs and enhancements

Ticketed repairs and enhancements may be contributed by any developer working independently or employed by any external entity. Minimum requirements include:

  • Must be specified in an existing or new ticket
  • Ticket includes release note wording
  • User acceptance tests and detailed specification documented in the ticket
  • Software in Python 3.5+ in the dev team agreed coding style (PEP 8 plus any variations published by the dev team)
  • Software patches in unified diff format; or
  • New software in a separate module or package; and
  • New user documentation (if necessary) in the same style as other documentation
  • Complete (100%) unit test coverage
  • If an external Developer does not have commit rights to the repository, such a patch would need to be submitted by email to someone who has commit permissions.
  • For enhancements, a signed Contributor License Agreement (CLA individual or corporate) on file with the SharedSDS Foundation

The CLA ensures that any source code or other contribution is free of restrictions having regard to the open source licence of the SharedSDS project. It assigns copyright or irrevocably grants all rights required for the Foundation to treat the contributed software as its own for open source distribution under the open source licence in use. Without a CLA, the Foundation would have difficulty protecting the project.