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 releases. Read Tracking Progress on your Project Board to learn more about how to work with projects.
The backlog board hosts issues, bugs and features which are not a part of a particular release board. While each issue is opened in
its corresponding repository, this board gives an aggregated view of all open issues across all repositories. The board has total of seven
columns. Any new issues or epics should typically be assigned to the
Backlog column. Epics which are candidates to be included in
the next release are moved to the
Next Version Candidate column. During planning, all epics from the
Next Version Candidate column are reviewed and triaged. Epics which are selected to be in the next release are moved to
the current release board. The next 3 columns sort issues by priority. All unassigned issues are sorted into these
three columns based on the priority discussed in the team meeting. Issues from these columns are ready to be worked on. Any leftover work
from the previous release goes to the
Work in Progress column. The
Close? column holds any issues/epics that can probably be closed for
Current release work is tracked in the latest board. The board has 5 columns. The first one,
Schedule and Epics, hosts all properly
triaged epics targeted for the current release and the schedule for the current release. Triaged issues are under the
To do column. When
an issue is being worked on, it is moved to
In Progress column. When a PR for the issue is pushed, the issue is moved to
column. The PR has the corresponding issue linked from the GitHub UI and is not tracked on the board. Once the PR is merged, the issue
is moved to
The Enhancements repository is used for tracking epics as issues, and their corresponding enhancement proposals (the epics design) as pull requests to the enhancements repository. Any medium or small enhancement should be opened as an issue in the relevant repository, or as a general Enhancement Request issue.
Submariner’s release is automated to a great extent. The release process documentation explains the details of a release. The release
automation is maintained in the releases repository. It also hosts
subctl binaries for all released versions.
In order to have more structure and clarity, we expand upon the standard GitHub issue and define 3 types of issues: Bugs, Tasks and Epics.
A bug is an issue which captures an error or fault in the project. If a bug meets the criteria of a blocker, it is considered a blocker bug.
If an issue prevents a feature (either new or existing) from operating correctly and there’s no sufficient workaround, it may be deemed as a blocker for a release such that the release cannot proceed until it is addressed.
A task defines a specific unit of work that can be stand-alone or part of an epic. Work on a bug is not a task. A task should be relatively
small and fit within the scope of a single sprint otherwise it should be broken down into smaller tasks or perhaps be defined as an epic.
Tasks that relate to ongoing maintenance (version bumps, image trimmings, CI and automation) will usually be small, unplanned tasks that
typically occur throughout each release cycle. The associated GitHub issue / PR should be labeled as
An epic is a collection of tasks which are required to accomplish a feature.
The Submariner project follows time based release cycles where each cycle is 16 weeks long. While blocking bugs may delay the general availability release date, new features will not.
Features that were partially implemented in a given release will be considered “experimental” and won’t 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 detailed in the following sections.
Most sprints will end with a milestone pre-release as detailed in the following sections. This allows the community and project members to verify the project is stable and test any fixes or features that were added during the sprint. A formal test day may be held to facilitate testing of the pre-release.
Each sprint ends on a boundary day which also marks the beginning of the next sprint. The boundary days occur on a Monday.
On the sprint boundary day we will:
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 a new release cycle starts is dedicated to planning the release. Planning covers the epics, tasks and bugs which are targeted for the next release version. Planning meetings will be held, focusing on the Backlog board.
In order for a task or an epic to be eligible for the next version, it needs to fulfill these requirements:
The project team will hold planning meetings, led by the project’s “scrum lead”. During these meetings, the project team will:
next-version-candidatelabel from transferred epics.
By the end of the planning week, the project team will have a backlog of epics and tasks and can commence working on the design phase. All epics for the next version will be on the release board, while all Small and Medium tasks will be left on the backlog board and worked on based on their priority.
Project members are expected to work on the design for any epic features assigned to them. During this sprint, project members will update their respective epics with any work identified during the design phase. Project members are encouraged to perform proof of concept investigations in order to validate the design and clarify specific work items.
In case additional work items are identified during the design, they should be opened as tasks and tracked under the respective epic. Such tasks are expected to follow the sizing guidelines from the 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. The code owners list is an aggregate list of the code owners of all Sumbariner repositories. As soon as the pull request is reviewed and merged, work on the epic can begin.
Project members are expected to review proposals from other members in addition to drafting their own proposals. 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 next release.
In lieu of demos, the project will host a design review at the end of the sprint. All the approved epics and their designs will be presented.
The milestone sprints are focused on development work for 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 should follow the defined guidelines.
Each sprint will end with a release to allow the community to test new features and fixed bugs. In total, three milestone sprints are planned:
As detailed in the sprints section, each milestone release 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 for
Any bugs found during the test days will need to be labeled with the appropriate
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.
rc1 release will be planned at the team’s discretion and has no expected date.
rc1 release is planned, the team will proceed with the general availability release.
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.
rc2 and beyond will delay the general availability release.
Once a release candidate is deemed stable and has no blocker bugs it will be released for general availability. Prior to releasing, the release manager will verify that there were no changes on the stable branches since the last release candidate. This ensures that no bugs could have been introduced to possibly affect the stability of the released version.
The new version will be announced per the announcement guidelines in the release process documentation, and release notes for the new release will need to be published.
The current release board will be closed, and all remaining items will be moved back to the backlog board. The items can then be considered for the next version, based on the planning guidelines.
During the week when the general availability release is performed, the next version will be planned. Additionally, a retrospective meeting for the last release cycle will be held. There will be no dedicated test day, as the release candidate has been tested and no changes have occurred since.
Release notes should be published for each GA version.
All new features and bug fixes of the release should be labeled with
release-note-needed and have a relevant release note
documented as part of the PR. Release notes submitted with PRs should be written in individual files in the
of the relevant repository.
The release note file name should contain a short description about the release note subject, prefixed with a date in the format
YYYYMMDD and end with a
.md suffix. The date part is the date the PR was first pushed.
The content of the file should be Markdown snippets, starting with
<!-- markdownlint-disable MD041 --> in the first line
to avoid failing over missing main header by the
Once a week, as part of the tasks and bugs triage meeting, the team will make sure that new bugs / tasks / PRs are properly
labeled and have the release notes documentation. When the version is ready for GA, all the notes can then be gathered
from issues / PRs using the
release-note-needed label and a pull request to the website repository should be opened.
After that point, the
release-note-handled label should be added to the issues / PRs. The following query can be use to identify
pending issues / PRs.
During a release, new work that was unknown during the planning phase will emerge. This work is typically one of three types:
The team triages tasks and bugs as part of a weekly meeting. The bugs can be worked on immediately, while other types of issues are described below.
In some cases, a task or an epic will be reported in the middle of a release cycle. Small and medium sized tasks will be triaged and prioritized in the same manner as other issues. Once triaged and prioritized, small and medium tasks can be worked on according to their priority.
Epics would need to undergo an exception process. The epic’s proponent would need to bring it up to discussion in the weekly community meeting. It’s up to the proponent to show why the new issue should take precedence over other pre-planned and triaged issues. A 50% approval from the Project Members in attendance at the meeting or having voted before the meeting is required for an epic to be accepted in the middle of the release. If the epic is approved during the exception process:
unplannedshould be added to it.
Test days are held in order to validate pre-released versions by the project members and the wider community. Any bugs opened on a test day will be triaged soon after.
The goals of these days are:
Test days will be led by one of the project members, who will be responsible for:
Should a bug be identified during a test day, it should be labeled with an appropriate