Software development life cycle


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

Roadmap items

At the very top, Sourcegraph uses roadmap issues, found in the 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.

Tracking issues

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.

Standard issues

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.

Additional artefacts

To convey additional context driving changes, Sourcegraph uses two other type of artefacts, that are referenced by GitHub issues:

  • PR-FAQ to communicate high-level product problems that need to be solved.
  • Request For Comments to communicate around specific problems and make decisions.


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.


See Design process.


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.

Verification and Testing

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.

Security is evaluated through automated vulnerability scanning and SAST during continuous integration.

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:

Maintenance and monitoring

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.

Team specifics

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 page under their own folder and linking toward it in this section, below this paragraph.

Contributing to this page

Changes to this pages impacts all teams and therefore must be reviewed by organization leaders as well as the Developer Experience team.