Skip to content

Latest commit

 

History

History
143 lines (96 loc) · 8.07 KB

DEVELOPMENT.md

File metadata and controls

143 lines (96 loc) · 8.07 KB
Raw

This file covers things that are good to know if you're developing or maintaining src. It is likely incomplete, and contributions would be most welcome!

Contents

Development

If you want to develop the CLI, clone the repository and build/install it with go install

cd src-cli/
go install ./cmd/src

You can also run it directly without installation:

go run ./cmd/src

Use debug build tag to debug batch changes functionality

Since src batch apply and src batch preview start up a TUI that gets updated repeatedly it's nearly impossible to do printf-debugging by printing debug information - the TUI would hide those or overwrite them.

To help with that, you can compile your src binary (or run the tests) with the debug build flag:

go build -tags debug -o ~/src ./cmd/src

This will cause the ./internal/batches/debug.go file to be included in the build. In that file the log default package logger is setup to log to ~/.sourcegraph/src-cli.debug.log.

That allows you to tail -f ~/.sourcegraph/src-cli.debug.log and use log.Println() in your code to debug.

Testing

src uses normal Go testing patterns, and doesn't require any other dependencies for its test suite to be run.

You can test the entire tool with:

go test ./...

Or just a single package with:

go test ./internal/batches/workspace

We adhere to the general Sourcegraph principles for testing, as well as the Go specific directions, at least to the extent they apply to a standalone tool like src.

Releasing

  1. Find the latest version (either via the releases tab on GitHub or via git tags) to determine which version you are releasing.
  2. (optional) If this is a non-patch release, update the changelog. Add a new section ## $MAJOR.MINOR to CHANGELOG.md immediately under ## Unreleased changes. Add new empty Added, Changed, Fixed, and Removed sections under ## Unreleased changes. Open a pull request with the new changelog. Get the pull request merged before completing the next step.
  3. VERSION=9.9.9 ./release.sh (replace 9.9.9 with the version you are releasing)
  4. GitHub will automatically perform the release via the Build and Release action. Once it has finished, you need to confirm:
    1. The brew formula shows the correct version. 
       brew info sourcegraph/src-cli/src-cli
    2. The npm library shows the correct version. 
      npm show @sourcegraph/src version
    3. The releases section of the repo sidebar shows the correct version.
  5. Make the necessary updates to the main Sourcegraph repo:
    1. Update the MinimumVersion constant in the src-cli package.
    2. Update the SRC_CLI_VERSION in tool_deps.bzl
    3. Update the sha256 hashes for the three src-cli-* targets in tool_deps.bzl. The easiest way to do this is to run the following command after updating SRC_CLI_VERSION, and extract the correct checksums for each target from the error message: 
      $ bazel build @src-cli-linux-amd64//:src-cli-linux-amd64 \
     @src-cli-darwin-amd64//:src-cli-darwin-amd64 \
     @src-cli-darwin-arm64//:src-cli-darwin-arm64

ERROR: java.io.IOException: Error downloading [...]_linux-amd64.tar.gz [...] Checksum was <new linux-amd64 checksum>

[...]
      After updating the checksums, rerun the command to verify that the values are correct.
    4. Run sg generate bazel (this may not result in any changes)
    5. Commit the changes, and open a PR.
  6. Once the version bump PR is merged and the commit is live on dotcom, check that the curl commands in the README also fetch the new latest version.

Patch releases

If a backwards-compatible change, such as a bug fix, is made after a backwards-incompatible one, the backwards-compatible one should be re-released to older instances that support it.

A Sourcegraph instance returns the highest patch version with the same major and minor version as MinimumVersion as defined in the instance. Patch versions are reserved solely for non-breaking changes and minor bug fixes. This allows us to dynamically release fixes for older versions of src-cli without having to update the instance.

To release a bug fix or a new feature that is backwards compatible with one of the previous two minor version of Sourcegraph, cherry-pick the changes into a patch branch, then follow the steps above to release the patch, specifying the appropriate patch VERSION. The Build and Release action will automatically create the appropriate versioned release, without overwriting the latest one.

Docker

We use Docker in a couple of different ways:

src-cli Docker image

Each release of src results in a new tag of the sourcegraph/src-cli Docker image being pushed to Docker Hub. This is handled by goreleaser's Docker support.

The main gotcha here is that the way goreleaser builds the Docker image is fairly difficult to replicate from the desktop: it builds a src binary without any runtime libc dependencies that can be installed in a scratch image, but unless you work on Alpine, your desktop is not configured to build Go binaries like that.

As a result, there are two Dockerfiles in this project. goreleaser uses Dockerfile.release, which is replicated in a multi-stage Dockerfile that builds src in a builder container to ensure it's built in a way that can be tested.

Testing the Docker image

If you need to test a change to the Dockerfile (for example, due to a Renovate PR bumping the base image), you should pull that change, then build a local image with something like:

docker build -t local-src-cli .

After which you should be able to run:

docker run --rm local-src-cli

and get the normal help output from src.

Dependent Docker images

src batch apply and src batch preview use a Docker image published as sourcegraph/src-batch-change-volume-workspace for utility purposes when the volume workspace is selected, which is the default on macOS. This Docker image is built by a Python script invoked by the GitHub Action workflow described in docker.yml.

To build and develop this locally, you can build and tag the image with:

docker build -t sourcegraph/src-batch-change-volume-workspace - < docker/batch-change-volume-workspace/Dockerfile

To remove it and then force the upstream image on Docker Hub to be used again:

docker rmi sourcegraph/src-batch-change-volume-workspace