diff --git a/doc/dev/product/index.md b/doc/dev/product/index.md index afa088b9802..28adf67593b 100644 --- a/doc/dev/product/index.md +++ b/doc/dev/product/index.md @@ -1,6 +1,6 @@ # Product -This document is about *how* we do product at Sourcegraph. For the *what*, see the [product roadmap](../roadmap/index.md). +This document is about *how* we plan product changes at Sourcegraph. For the *what*, see the [product roadmap](../roadmap/index.md). ## Goals @@ -71,7 +71,9 @@ When we have relaxed this in the past, the results have been bad and the overwhe We receive tons of feature request and bug reports, more than we can handle. This means we must frequently say "no" or prioritize things less urgently than some people would like. Our job is to find the most important things to work on. -## Product manager +## Roles + +### Product manager The product manager is responsible for prioritization, which means ensuring the following is true: @@ -89,3 +91,40 @@ The right mix of these 3 things depends on the team and what they're working on - For other teams, the PM will be the first to respond to and prioritize issues that are filed on the team. No matter the chosen mix, the PM is still responsible for prioritization. For example, if the PM doesn't effectively educate the devs so they can plan and triage well, then the PM needs to step up on planning and triage (as a backstop). + +### Tech lead + +Each project has one tech lead. A tech lead serves in that role for one or more release cycles. + +The tech lead is responsible for making sure the following two statements are true: + +> The issues for the current release milestone describe the problem/solution. +> +> The issues for the current release milestone are completed (closed) before the release. + +The following sections give more details. + +#### The issues for each release milestone are completed (closed) before the release. + +This means the tech lead needs to do 2 things: + +- **Estimate** at planning time what can get done in the time alotted for a release milestone. +- **Reschedule** issues continuously into/from the milestone depending on the pace and [triage](../issues.md#triage). + +It's impossible to estimate perfectly, so the tech lead needs to continuously monitor the team's progress and make adjustments accordingly. + +If it looks like the team won't be able to complete all planned issues by the release date, the tech lead **must** communicate this in the #product channel and follow up with a combination of: + +- helping unblock or accelerate the work of individual teammates +- descoping issues in this milestone +- deferring issues to a later milestone +- getting help from other people on certain issues + +The [product manager](#product-manager) can help here, especially with product and priority questions for descoping or deferring work. + +#### The issues for each release milestone describe the problem/solution. + +This means the tech lead needs to do 2 things: + +- Ensure the issues for feature work have enough information for the devs who are implementing the feature. +- Gather information for bug reports (including documenting/automating how other people can supply the info needed to diagnose/fix the bug). diff --git a/doc/dev/release_issue_template.md b/doc/dev/release_issue_template.md new file mode 100644 index 00000000000..002d7cbb1f1 --- /dev/null +++ b/doc/dev/release_issue_template.md @@ -0,0 +1,86 @@ + + +# MAJOR.MINOR Release (YYYY-MM-DD) + +## No later than 5 working days before release (YYYY-MM-DD) + +- [ ] Choose dates/times for the steps in this release process and update this issue template accordingly. Note that this template references _working days_, which do not include weekends or holidays observed by Sourcegraph. +- [ ] Send message to #dev-announce with a link to this tracking issue to notify the team of the release schedule. +- [ ] Private message each teammate who has open issues in the milestone and ask them to remove any issues that won't be done three working days before the release. + +## 3 working days before release (YYYY-MM-DD) + +- [ ] **HH:MM AM/PM PT** Create the branch for this release off of master (e.g. `3.0`) and tag the first release candidate (e.g. `v3.0.0-rc.1`). +- [ ] Add a new section header for this version to the [CHANGELOG](https://github.com/sourcegraph/sourcegraph/blob/master/CHANGELOG.md#unreleased) immediately under the `## Unreleased changes` heading. Commit and `git push` this change directly to upstream `master`. +- [ ] Send a message to #dev-announce to announce the release candidate. +- [ ] Run Sourcegraph Docker image with no previous data. + - [ ] `CLEAN=true IMAGE=sourcegraph/server:$NEWVERSION ./dev/run-server-image.sh` + - [ ] Initialize the site by creating an admin account. + - [ ] Add a public repository (i.e. https://github.com/sourcegraph/sourcegraph). + - [ ] Add a private repository (i.e. https://github.com/sourcegraph/infrastructure). + - [ ] Verify that code search returns results as you expect (depending on the repositories that you added). + - [ ] Verify that code intelligence works as you expect. + - [ ] Go to definition works in Go. + - [ ] Go to definition works in TypeScript. + - [ ] Find references works in Go. + - [ ] Find references works in TypeScript. +- [ ] Upgrade Sourcegraph Docker image from previous released version. + - [ ] `CLEAN=true IMAGE=sourcegraph/server:$OLDVERSION ./dev/run-server-image.sh` + - [ ] Initialize the site by creating an admin account. + - [ ] Add a public repository (i.e. https://github.com/sourcegraph/sourcegraph). + - [ ] Add a private repository (i.e. https://github.com/sourcegraph/infrastructure). + - [ ] `CLEAN=false IMAGE=sourcegraph/server:$NEWVERSION ./dev/run-server-image.sh` + - [ ] Verify that code search returns results as you expect (depending on the repositories that you added). + - [ ] Verify that code intelligence works as you expect. + - [ ] Go to definition works in Go. + - [ ] Go to definition works in TypeScript. + - [ ] Find references works in Go. + - [ ] Find references works in TypeScript. +- [ ] Run Sourcegraph on a clean Kubernetes cluster with no previous data. + - [ ] Initialize the site by creating an admin account. + - [ ] Add a public repository (i.e. https://github.com/sourcegraph/sourcegraph). + - [ ] Add a private repository (i.e. https://github.com/sourcegraph/infrastructure). + - [ ] Verify that code search returns results as you expect (depending on the repositories that you added). + - [ ] Verify that code intelligence works as you expect. + - [ ] Go to definition works in Go. + - [ ] Go to definition works in TypeScript. + - [ ] Find references works in Go. + - [ ] Find references works in TypeScript. +- [ ] Upgrade Sourcegraph on a Kubernetes cluster. + - [ ] Initialize the site by creating an admin account. + - [ ] Add a public repository (i.e. https://github.com/sourcegraph/sourcegraph). + - [ ] Add a private repository (i.e. https://github.com/sourcegraph/infrastructure). + - [ ] Verify that code search returns results as you expect (depending on the repositories that you added). + - [ ] Verify that code intelligence works as you expect. + - [ ] Go to definition works in Go. + - [ ] Go to definition works in TypeScript. + - [ ] Find references works in Go. + - [ ] Find references works in TypeScript. +- [ ] Add any [release blocking](releases.md#blocking) issues as checklist items and start working to resolve them. + +## As necessary + +- `git cherry-pick` commits from `master` into the release branch. +- Re-test any flows that might have been impacted by commits that have been cherry picked into the release branch. +- Tag additional release candidates. + +## 1 working day before the release (YYYY-MM-DD) + +- [ ] **HH:MM AM/PM PT** Tag the final release. +- [ ] Send a message to #dev-announce to announce the final release. +- [ ] Verify that all changes that have been cherry picked onto the release branch have been moved to the approriate section of the [CHANGELOG](https://github.com/sourcegraph/sourcegraph/blob/master/CHANGELOG.md) on `master`. +- [ ] Wait for the final Docker images to be available at https://hub.docker.com/r/sourcegraph/server/tags. +- [ ] [Update the image tags](https://github.com/sourcegraph/deploy-sourcegraph/blob/master/README.dev.md#updating-docker-image-tags) in [deploy-sourcegraph](https://github.com/sourcegraph/deploy-sourcegraph) (e.g. [d0bb80](https://github.com/sourcegraph/deploy-sourcegraph/commit/d0bb80f559e7e9ef3b1915ddba72f4beff32276c)) +- [ ] Wait for Renovate to pin the hashes in deploy-sourcegraph (e.g. [#190](https://github.com/sourcegraph/deploy-sourcegraph/pull/190/files)), or pin them yourself. +- [ ] In deploy-sourcegraph, tag the release (e.g. `v3.0.0`) and create the release branch off of master at this commit (e.g. `v3.0`). + +## On or before release day (YYYY-MM-DD) + +- [ ] **HH:MM AM/PM PT** Merge the blog post. ). +- [ ] Update `latestReleaseKubernetesBuild` and `latestReleaseDockerServerImageBuild` in `master`. +- [ ] Review all issues in the release milestone. Backlog things that didn't make it into the release and ping issues that still need to be done for the release (e.g. Tweets, marketing). +- [ ] Close this issue. diff --git a/doc/dev/releases.md b/doc/dev/releases.md index f36e39b7ed4..46491ee493f 100644 --- a/doc/dev/releases.md +++ b/doc/dev/releases.md @@ -1,83 +1,128 @@ # Releases -This document describes how we plan and ship releases at Sourcegraph. +This document describes how we release Sourcegraph. + +## Goal + +The goal of our release process is to make releases boring, regular, and eventually, automated. ## Releases are monthly -We ship a release on the 20th day of each month. (Except in February 2019, where we will ship on the 4th and 20th.) Why the 20th? Because it's a day number that we can hit each month (any other number would result in a December release that comes out too close to Christmas, or a January release that comes out too soon after New Year's Day). +We release Sourcegraph **by** 10am PT on the 20th day of each month. + +"Release" means: +- The Docker images are available for download. +- The blog post is published. +- The release is documented on docs.sourcegraph.com. The release always ships on time, even if it's missing features or bug fixes we hoped to get in ([why?](https://about.gitlab.com/2015/12/07/why-we-shift-objectives-and-not-release-dates-at-gitlab/)). -## Milestones and issues +### Why the 20th? -Each release has a GitHub milestone ([in all repositories](issues.md#multiple-repositories)) whose name is the version number, such as `3.1`: +We don't want to ship a release too late in December because the Sourcegraph team has a scheduled break December 24 through January 1. -- A release milestone's [issues](issues.md) constitute the release plan (i.e., the canonical definition of the work for the release). -- A release is ready when its milestone has zero open issues ([across all repositories](issues.md#multiple-repositories)). +### Why aren't releases continuous? -The issues for a release come from two sources: +Although [Sourcegraph.com](https://sourcegraph.com) is continuously deployed (from sourcegraph/sourcegraph@`master`), the version of Sourcegraph that customers use is not continuously released or updated. This is because: -- [product planning](product/index.md#planning) (work planned for the release ahead of time) -- [issue triage](issues.md#triage) (issues filed at any time) +- We don't think customers would be comfortable with a continuously updated service running on their own infrastructure, for security and stability reasons. +- We haven't built the automated testing and update infrastructure to make continuous customer releases reliable. -### Process +In the future, we may introduce continuous releases if these issues become surmountable. -A release cycle is [1 month](#releases-are-monthly). Each release cycle goes as follows (where T is the start of the release cycle, beginning the moment when the previous release ships): +## Versioning -- Between T-2 weeks and T: for all projects, [product planning](product/index.md#planning) for the release is done; tracking issues and all other foreseen work issues exist. - - Because [product planning is continuous](product/index.md#product-planning-is-continuous), these may have been ready even earlier for certain projects. -- Between T and T+1 month: - - Each project team works on "making the tracking issue come true" by closing all project issues in the release milestone. - - [Triage issues](issues.md#triage) as they come in (which may require updates to the project plan for the current release because they supply us with new information). - - TODO: document testing and release preparation -- T+1 month: - - Release! (TODO: document process and also how we do it if the 20th is on a non-work day) - - [Start a retrospective.](retrospectives/index.md#how-to-lead-a-retrospective) +[Monthly releases](#releases-are-monthly) of Sourcegraph increase the minor version number (e.g. 3.1 -> 3.2). These releases **never** require any manual migration steps. -## Roles +Patch releases (e.g. 3.0.0 -> 3.0.1) are released on an as-needed basis to fix bugs and security issues. These releases **never** require any manual migration steps. -### Tech lead +On rare occasions we may decide to increase the major version number (e.g. 2.13 -> 3.0). These releases **may** require manual migration steps. -Each project has one tech lead. A tech lead serves in that role for one or more release cycles. +## Release process -The tech lead is responsible for making sure the following two statements are true: +What is the process we follow to release? -> The issues for the current release milestone are completed (closed) by the release. -> -> The issues for the current release milestone describe the problem/solution. +### Release captains -The following sections give more details. +The release captain is _responsible_ for managing the release process and ensuring that the release happens on time. The release captain may _delegate_ work to other teammates, but such delegation does not absolve the release captain of their responsibility to ensure that delegated work gets done. -#### The issues for each release milestone are completed (closed) by the release. +No later than 5 _working days_ before the release day the release captain creates a tracking issue using the [release issue template](release_issue_template.md) and assigns it to themself to complete. -This means the tech lead needs to do 2 things: +### Schedule -- **Estimate** at planning time how much can get done in the time alotted for a release milestone. -- **Reschedule** issues continuously into/from the milestone depending on the pace and [triage](issues.md#triage). +| Version | Captain | Release Date | +|---------|---------|--------------| +| 3.0 | @nicksnyder | 2019-02-07 (Wednesday) | +| 3.1 | @nicksnyder | 2019-02-20 (Wednesday) | +| 3.2 | @nicksnyder | 2019-03-20 (Wednesday) | +| 3.3 | @beyang | 2019-04-20 (Saturday) | +| 3.4 | @ggilmore | 2019-05-20 (Monday) | +| 3.5 | @keegancsmith | 2019-06-20 (Thursday) | +| 3.6 | @slimsag | 2019-07-20 (Saturday) | +| 3.7 | @ijsnow | 2019-08-20 (Tuesday) | +| 3.8 | @tsenart | 2019-09-20 (Friday) | +| 3.9 | @lguychard | 2019-10-20 (Sunday) | +| 3.10 | @attfarhan | 2019-11-20 (Wednesday) | +| 3.11 | @chrismwendt | 2019-12-20 (Saturday) | +| 3.12 | @vanesa | 2020-01-20 (Monday, MLK) | +| 3.13 | @felixfbecker | 2020-02-20 (Thursday) | -It's impossible to estimate perfectly, so the tech lead needs to continuously monitor the team's progress and make adjustments accordingly. +Release captains may trade rotations with each other by updating this schedule. -If it looks like the team won't be able to complete the issues by the release, the tech lead **must** mention this in the #product channel and needs to do some combination of: +If a release captain is unexpectedly unavailable and did not arrange a replacement, the captain from the previous release becomes the release captain for the current release. -- helping unblock or accelerate the work of individual teammates -- descoping issues in this milestone -- deferring issues to a later milestone -- getting help from other people on certain issues +### Release branches -The [product manager](product/index.md#product-manager) can help here, especially with product and priority questions for descoping or deferring work. +Each major and minor release of [Sourcegraph](https://github.com/sourcegraph/sourcegraph) has a long lived release branch (e.g. `3.0`, `3.1`). Individual releases are tagged from these release branches (e.g. `v3.0.0-rc.1`, `v3.0.0`, `v3.0.1-rc.1`, and `v3.0.1` would be tagged from the `3.0` release branch). -#### The issues for each release milestone describe the problem/solution. +To avoid confusion between tags and branches: -This means the tech lead needs to do 2 things: +- Tags are always the full semantic version with a leading `v` (e.g. `v2.10.0`) +- Branches are always the dot-separated major/minor versions with no leading `v` (e.g. `2.10`). -- Ensure the issues for feature work have enough information for the devs who are implementing the feature. -- Gather information for bug reports (including documenting/automating how other people can supply the info needed to diagnose/fix the bug). +Development always happens on `master` and changes are cherry picked onto release branch as necessary with the approval of the release captain. -## We don't release continuously +#### Example -Although [Sourcegraph.com](https://sourcegraph.com) is continuously deployed (from sourcegraph/sourcegraph@`master`), the version of Sourcegraph that customers use is not continuously released or updated. This is because: +Here is an example git commit history: -- We don't think customers would be comfortable with a continuously updated service running on their own infrastructure, for security and stability reasons. -- We haven't built the automated testing and update infrastructure to make continuous customer releases reliable. +1. The release captain creates the `3.0` release branch at commit `B`. +1. The release captain tags the release candidate `v3.0.0-rc.1` at commit `B`. +1. A feature is commited to `master` in commit `C`. It will not ship in `3.0`. +1. An issue is found in the release candidate and a fix is committed to `master` in commit `D`. +1. The release captain cherry picks `D` from `master` into `3.0`. +1. The release captain tags `v3.0.0` on the `3.0` release branch. +1. Development continues on master with commits `E`, `F`, `G`, `H`. +1. Commit `F` fixes a critical bug that impacts 3.0, so it is cherry picked onto the `3.0` release branch and `v3.0.1` is tagged. +1. The release captain (different person) for 3.1 creates the `3.1` release branch at commit `H` and a new release cycle begins. +1. Commit `J` fixes a critical bug that impacts both 3.0 and 3.1, so it is cherry picked into both `3.0` and `3.1` release branches and new releases are tagged (`v3.0.2`, `v3.1.2`). -In the future, we may introduce continuous releases if these issues become surmountable. +``` +A---B---C---D---E---F---G---H---I---J---K---L (master branch) + \ \ + \ `---v3.1.0-rc.1---I'---v3.1.0---J'---v3.1.2 (3.1 release branch) + \ + `---v3.0.0-rc.1---D'---v3.0.0---F'---v3.0.1---J'---v3.0.2 (3.0 release branch) +``` + +### Issues + +How do we deal with issues that are found during the release process? + +#### Blocking + +The release always ships on time, even if it's missing features or bug fixes we hoped to get in ([why?](https://about.gitlab.com/2015/12/07/why-we-shift-objectives-and-not-release-dates-at-gitlab/)). + +There are only three kinds of issues that are eligible to block a release: + +1. Issues that literally prevent us from tagging a release (i.e. our CI logic to produce builds from git tags is broken). +2. Issues that fundamentally break our product for a _majority_ of our customers and don't have acceptable workarounds. +3. Critical security _regressions_ from the previous release. + +Only the release captain can label something as release blocking. + +The release captain has unlimited power to make changes to the release branch to resolve release blocking issues. As soon as a release blocking issue is identified, the release captain should decide the least risky way to relosve the issue as soon as possible. A good default action is to identify and revert offending commits from the release branch. In the worst case, this could involved recreating the release branch from an earlier commit on master. Project owners can work on master to fix the issue, and if the issue is resolved in time, revert the revert and cherry-pick the fix on the release branch. + +#### Non-blocking + +Most issues are non-blocking. Fixes to non-blocking issues can be fixed in `master` by the code owner who can then `git cherry-pick` those commits into the release branch with the approval of the release captain. Alternatively, broken features can be reverted out of the release branch or disabled via feature flags if they aren't ready or are too buggy. diff --git a/enterprise/cmd/server/README.md b/enterprise/cmd/server/README.md index 26645d8f162..57bab3be27e 100644 --- a/enterprise/cmd/server/README.md +++ b/enterprise/cmd/server/README.md @@ -1,111 +1,3 @@ -# `sourcegraph/server` release process +# Sourcegraph Server -The user-facing documentation lives in [sourcegraph/sourcegraph `doc/`](https://github.com/sourcegraph/sourcegraph/tree/master/doc) and is hosted on [docs.sourcegraph.com](https://docs.sourcegraph.com). - -This file documents information relevant to developers at Sourcegraph. - -## Publishing a new version - -#### (0) Update the CHANGELOG - -1. Update [CHANGELOG](../../CHANGELOG.md) on `master` (even if the release will be cut from a different branch). - - 1. If this is a major or minor release, move any `Unreleased changes` under their own section - for the new `VERSION` you are releasing. - 1. If this is a patch release, create a new section for the `VERSION` you are releasing and - selectively move changelog items from `Unreleased changes` to this section. - - **Remove any empty sections in the changelog**. - -1. Commit and `git push` this change directly to upstream `master`. - -#### (1) Use the proper release branch - -- New major releases (e.g. `v3.0.0`) should be tagged from `master`. Once you have tagged the release, create a long lived branch from that tag for patches to that release (e.g. `3.0`). -- New minor releases (e.g. `v3.1.0`) should be tagged from `master`. Once you have tagged the release, create a long lived branch from that tag for patches to that release (e.g. `3.1`). -- New patch releases (e.g. `v3.1.1`) should be tagged from the existing patch branch for the release being patched (e.g. `3.1`). - - Commits necessary for a patch release are cherry-picked from `master` into the patch branch - before tagging a release. - - Do NOT commit any fixes or features into a patch release that are not yet in - `master`. Otherwise, you will end up breaking the validity of the changelog, as such orphaned - updates will be silently regressed in the next major/minor release. - -To avoid confusion between tags and branches: - -- Tags are always the full semantic version with a leading `v` (e.g. `v2.10.0`) -- Branches are always the dot-separated major/minor versions with no leading `v` (e.g. `2.10`). - -#### (2) Create the release candidate - -Push your release branch upstream. Remember the commit hash. This is the commit you will tag as the official release if testing goes well. - -If you are creating a patch release, you will want to push to `docker-images-patch/server` to create a docker image that you can test. - -#### (3) Test - -1. Look in Buildkite to find the image hash (e.g. `sha256:043dce9761dd4b48f1211e7b69c0eeb2a4ee89d5a35f889fbdaea2492fb70f5d`) for the `sourcegraph/server` docker image step ([example](https://buildkite.com/sourcegraph/sourcegraph/builds/18738#eca69bac-2efd-4e99-82bd-99e9edd986f9)) of the release candidate build you just created in step 2. - -1. Run the latest container from a clean state: - - ```bash - CLEAN=true IMAGE=sourcegraph/server@$IMAGE_HASH ./dev/run-server-image.sh - ``` - -1. Do some manual testing: - - Create admin account - - Add a repo - - Do a search - - Open a code file and see code intel working -1. Run the previous minor version (e.g. if releasing 2.9.0 then install 2.8.0) from a clean state: - - ```bash - CLEAN=true IMAGE=sourcegraph/server:$PREVIOUS_VERSION ./dev/run-server-image.sh - ``` - -1. Do some manual testing to create state that we can ensure persists after the update: - - Create admin account - - Add a repo - - Do a search - - Open a code file and see code intel working -1. Stop the old container and run the new container without cleaning the data: - - ```bash - CLEAN=false IMAGE=sourcegraph/server@$IMAGE_HASH ./dev/run-server-image.sh - ``` - -1. Verify that - - You don't need to recreate an admin account. - - The repo you added is still added. - - Search works. - - Code intelligence works. - -#### (4) Release the `sourcegraph/server` Docker image - -```bash -git fetch -git tag v$VERSION ${COMMIT_FROM_STEP_2} -git push --tags -``` - -#### (5) Update the public documentation - -1. Check out a new branch in the [sourcegraph/website](https://github.com/sourcegraph/website) repository. -1. Update the old version number in the documentation to be the version number you are releasing [by editing this React component](https://github.com/sourcegraph/website/blob/master/src/components/ServerVersionNumber.tsx). -1. Copy over the new changelog entries from [sourcegraph/sourcegraph](https://github.com/sourcegraph/sourcegraph). -1. Copy the schema from the released git commit to the [sourcegraph/website](https://github.com/sourcegraph/website) repo: - ```bash - cd $WEBSITE_REPO - cp $GOPATH/src/github.com/sourcegraph/sourcegraph/schema/site.schema.json utils/ - ``` -1. Create the PR on the website repository and merge it. - -#### (6) Notify existing instances that an update is available - -1. Checkout the `master` branch in the [sourcegraph/sourcegraph](https://github.com/sourcegraph/sourcegraph) repository. -1. Update ../cmd/frontend/internal/app/pkg/updatecheck/handler.go's `latestReleaseDockerServerImageBuild` to the - semver version string of the new version. -1. Commit and `git push` this change directly to the `master` branch. - -`sourcegraph/server` version `VERSION` has been released! - -You should also [release the new version for Sourcegraph cluster deployment](https://github.com/sourcegraph/deploy-sourcegraph/blob/master/README.dev.md#cutting-a-release). +This directory contains the code which makes up the `sourcegraph/server` Docker image which runs Sourcegraph on a single node.