This document explains the workflow for driving changes on the Sourcegraph software application.
Sourcegraph uses GitHub issues to track and drive changes to its application. They are the single source of truth, and are structured as following:
- Roadmap issues
- Tracking issues
- Standard issues
- Tracking issues
At the very top, Sourcegraph uses roadmap issues, found in the product and engineering roadmap tracker list objectives for each quarter in individual issues. Each individual issue is tagged with their owning organization, owning team and assignees, who are in charge of updating the issue during the quarter.
A roadmap issue contains the following sections:
- Problem definition
- Measure of success
- Solution summary
- What specific customers are we iterating on the problem with?
- Impact on use cases
- Delivery plan
The purpose of these sections is make the objectives definition and understanding the current status clear for every teammate, regardless of their role.
A tracking issue is a GitHub issue that captures the planned and on-going work of a team’s milestone, project, RFC, goal or anything else of the sort and are mentioned in roadmap items they relate to. This artifact is a medium used for planning, progress check-ins and stakeholder communication.
A detailed guide about tracking issues is available.
A standard issue captures a task, a bug or an explocation owned by a team (assigned through a label of the form
team/NAME). Other expectations toward the issue content and labels are up to its owning team.
A detailed page about issues is available.
To convey additional context driving changes, Sourcegraph uses two other type of artefacts, that are referenced by GitHub issues:
The flow starts with a GitHub issue that will be the single source of truth for the initiative and will be referenced by all produced artefacts.
Designing at Sourcegraph starts with a design document: a PD, an RFC or simply a description in the GitHub issue.
The outcome of the design step is an updated Product Document that links to design work and user research that supports it. The design team follows product design principles and iteratively solidifies its work into deliverables that can be shipped in order to measure and evaluate the solution design.
When a RFC or PD reaches the REVIEW phase, reviewers and approvers scrutinize the proposed solution, seeking to establish it if meets the stated requirements.
A detailed version of the design process is available. This process may also include engineering discovery work that explores the problem space to frame the right boundaries for the implementation phase and to surface potential problems as soon as possible.
With the help of a Product Manager, the relevant engineering teams divide the necessary work into smaller tracked units of effort with the management system of their choice. This optionally takes the form of a tracking issue. Embedding security in the developement process, security ambassadors are present to provide early feedback and assistance on security related requirements.
Engineering teams iterate and plan the implementation of these units of work on their own time. The Product Manager is ultimately responsible for the conformance of the result to the requirements stated in the Product Document or RFC, though an Engineering Manager or Engineer can also lead the work.
If complex problems surface during this step, an RFC can be created to frame the discussions around that particular problem to provide an adequate solution.
The testing phase ensures conformance to the requirements stated in the Product Document/RFC/Ticket and to appropriate standards for service and security. The solution is scrutized to evaluate if the requirements stated in the design phase are met.
If necessary, the changes will be deployed on an internal Sourcegraph instance to be internally tried until enough confidence is reached.
If the change is a feature, it may initially only be available behind a feature flag in order to provide a mechanism to disable it if needed, as well as ensure that the continuous releasability contract is maintained.
Sourcegraph uses two different mechanisms to deploy its changes in production:
The Product Manager and the owning team are in charge of ensuring that the newly introduced changes are meeting the requirements, observing the behaviour in the production environments through monitoring, feedback or bug reports from customers. If any incorrect behaviour is found or a requirement isn’t met, they write corrective changes to fix those issues.
Optionally, teams can specialize this document to further detail their own process, as long as it is compatible with the default SDLC covered in this document by creating a
sdlc.md page under their own folder and linking toward it in this section, below this paragraph.
Changes to this pages impacts all teams and therefore must be reviewed by organization leaders as well as the Developer Experience team.