This guide outlines the process which developers need to follow when contributing to the Submariner project. Developers are expected to read and follow the guidelines outlined in this guide and in the other contribution guides, in order for their contributions to the project to be addressed in a timely manner.
Submariner uses GitHub projects to manage a particular release. Read here to know more on how to work with projects.
Backlog board is maintained to host any issues or features that would not land in the current release.
Current release work is tracked at 0.13 board
All enhancement proposals need to be submitted to the enhancements repository. To submit a new enhancement proposal, raise an Enhancement Request issue on the repository.
Submariner release is automated to a great extend. This section explains the details of a release. The code is maintained in the releases repository
In GitHub there is only one type of issues. In order to have a more structured view of the current state of a release, we distinguish between 3 types of issues: Bugs, Tasks and Epics.
A bug is an issue which capture an error or fault in the project. When a bug is met the criteria of a blocker bug, it is considered as a blocker bug.
A blocker bug is defined as something that prevents the system from running, or blocks the system from testing (either a regression on an existing feature, with the same test as used previously, or a new feature which can’t be tested).
A task is a description of a specific work needed to be done. A task can be part of an epic, or a stand-alone. If a task is estimated to take more than 1 sprint to worked on, it should be break down to smaller tasks.
An Epic is a series of tasks which are required to accomplish a feature.
- Epics should all live inside enhancements repo
- Only include work directly related to
Submarinerproject - Don’t start working on an epic if the design is not done
- Don’t add new epics to a release after the planning is done
- Have clear and agreed acceptance criteria
- Breaking down an epic:
- First, use the template to assess any common tasks (i.e. operator support) and open issues for them
- Implementation tasks should be up to medium in size
- Don't create nested tasks/issues - if a task needs to be broken down, create separate tasks and list them all under the epic
The Submariner project follows time based release cycles, each cycle is 16 weeks long. Blocking bugs might cause a delay in the final release date, while new features will never be a cause fo delaying the release.
Features that were partially implemented in a given release will be considered "experimental" and will not have any support commitment.
Each cycle will result in either a minor version bump or a major version bump in case backwards compatibility can't be maintained.
Sprints are 3 week periods which encapsulate work on the release. Most sprints focus on active development of the current version, while some focus on additional aspects such as design and stabilization. Specific sprints and their contents are details in the following sections.
Each sprint starts and ends on a boundry day, when one sprint ends another one begins. The boundry day is Monday.
On the sprint boundry day we will:
- Perform a milestone release (When applicable).
- Have release related meetings, instead of any usually recurring meetings:
- Grooming (30 minutes):
- Making sure epics are on track.
- Reviewing the Definition of Done for each epic.
- Moving epics back to the Backlog, in case they're de-prioritized.
- Retrospective (30 minutes):
- Looking back at the task sizes and assessing if they were correct.
- General process improvement.
- Demos (30 minutes):
- Any enhancements (or parts of) that have been delivered in the sprint.
- Other interesting changes (e.g. refactors) that aren't part of any epic.
- In case there's nothing to showcase, this meeting will be skipped.
- Grooming (30 minutes):
Source: https://docs.google.com/drawings/d/1wZCogcChCkX2PqoIuTx9I_iOgJuwsYjChVopq1nfqeM
Each release follows a fixed timeline, with 4 development sprints and one final sprint for stabilization. The version will be released one week after the last sprint, and the planning work for the next release will begin.
The following sections explain the activities of each sprint.
The week before the release is dedicated to planning the next release. Planning accounts for tasks and bugs which we intend to solve in the next version. Planning meetings will be held, focusing on the [Backlog board].
For a task to be eligible for the next version, it needs to fulfill these requirements:
- Be part of the [Backlog board].
- Have a
next-version-candidatelabel. - Have a description detailing what is the issue and optionally how is it going to be solved.
- Have an apropriate sizing label, according to amount of work expected for a single person to completely deliver the task:
- Small: Work is contained in one sprint and is expected to take less than half the sprint.
- Medium: Work is contained in one sprint and is expected to take most of the sprint.
- Large: Work is contained within a release (two-three sprints).
- Extra-Large = Work can't be contained within a release and would span multiple releases.
- Any Large or Extra-Large task must be converted to an epic.
- In case of an epic:
- Be an issue in the [enhancements] project.
- Adhere to the [epic template].
- Have a high level break down of the expected work, corresponding to the "Definition of Done".
The project team will hold planning meetings, led by the project's "scrum master". During these meetings, the project team will:
- Prioritize and assign tasks for the next version.
- Only tasks adhering to the described requirements will be considered.
- Transfer tasks to the next release board according to the capacity of the team to deliver it.
- Remove the
next-version-candidatelabel from transferred tasks.
By the end of the pre-planning week, the project team should have a backlog of tasks and can commence working on the design phase.
Project members are expected to work on feature design for any epic feature assigned to them. During this sprint, project members will update their respective epics with any work identified during the design page. Project members are encouraged to perform "proof of concept" investigations in order to consolidate the design and understand any necessary work items.
In case additional work is identified during the design, it should be opened as tasks and tracked under the respective epic. Such tasks are expected to follow the sizing guidelines from the Pre-Planning stage. Specifically, tasks that are themselves epics due to their size should be identified and treated as such.
Design proposals for epics should be submitted as [pull requests to the enhancements repository], detailing the proposed design, any alternatives, and any changes necessary to the Submariner projects and APIs.
The [pull requests to the enhancements repository] will be reviewed during the sprint, discussing any necessary changes or reservations. Any pull request will need approval from at least 50% of the [code owners of the enhancements repository]. When the pull request is reviewed and merged, work on the epic can begin.
Project members are expected to utilize the sprint to draft their own proposals, and review proposals from other participants. If a project member has finished work on their proposal, they're encouraged to help with the other ongoing proposals.
Only epics which were planned for the release will be reviewed at this stage. Any epic that was unplanned but seeks inclusion in the release should follow the exception process. The same process will have to be followed for any epic that was planned but has not been agreed upon by the end of this sprint. Any such epics will be moved back to the Backlog board and reconsidered for the release.
At the end of the sprint, a special release m0 signifying the 0th milestone will be released.
This release allows the project contributors to start working on the next version, without fear of versioning collisions with
point-releases from the previous release.
The milestone sprints are focused on development, encapsulating work on various tasks and bugs. Project members will work on any planned tasks and bugs, and will also work on unplanned bugs should they arise. Any unplanned work will have to follow the defined guidelines.
Each sprint will end with a milestone release which allows the project community to test newly added features and fixed bugs. In total, three milestone sprints are planned:
- Two milestones ending with releases of milestone
m1and milestonem2. - The last sprint will end with the release of the release candidate
rc0.
As detailed in the sprints section, each milestone releases will be followed by a test day and the sprint meetings.
At the end of 12 weeks, the project is ready to be released and the pre-release rc0 is created.
At this point, as detailed in the release process documentation, stable branches are created and the project goes into feature freeze
for the release branches.
Two test days will take place after the release is created, as the project members make sure the release is ready to be
generally available.
Any bugs found during the test days will need to be labeled with the appropriate testday label.
The project members will triage the test day bugs and identify any high priority ones that should be addressed before general availability.
If any high priority bugs were identified after rc0, a new release rc1 will be planned to allow for fixing them.
The rc1 release will be planned according to the team's discretion and has no expected date.
If no rc1 release is planned, the team will proceed with the general availability release.
Starting from rc1, the stable branches enter a code freeze mode - only blocker bugs will be eligible for merging.
If a bug is fixed and merged during the code freeze, a new release candidate needs to be prepared and tested.
Releasing rc2 and beyond will delay the general availability release.
To be expanded
To be expanded
To be expanded
To be expanded
To be expanded