Skip to content

Commit 06892ce

Browse files
authored
Add additional docs on installations and releases. (#86)
1 parent 70f0abf commit 06892ce

1 file changed

Lines changed: 25 additions & 2 deletions

File tree

README.md

Lines changed: 25 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,13 @@ If there is something you'd like to see Sourcegraph be able to do from the CLI,
1818

1919
## Installation
2020

21-
**NOTE:** To get the best version for _your_ Sourcegraph instance, simply replace `sourcegraph.com` in the commands below with your own Sourcegraph URL and the latest version compatible with your instance will be provided. If you are running a Sourcegraph version older than 3.13, run the commands below instead.
21+
For Sourcegraph 3.13 and newer, the preferred method of installation is to ask _your_ Sourcegraph instance for the latest compatible version. To do this, replace `https://sourcegraph.com` in the commands below with the address of your instance.
22+
23+
For Sourcegraph 3.12 and older, run the following commands verbatim (against sourcegraph.com) or install from one of the published [releases on GitHub](https://github.com/sourcegraph/src-cli/releases).
24+
25+
```
26+
https://github.com/sourcegraph/src-cli/releases/download/{version}/{binary}
27+
````
2228
2329
#### Mac OS
2430
@@ -108,4 +114,21 @@ go get -u github.com/sourcegraph/src-cli/cmd/src
108114
3. Travis will automatically perform the release. Once it has finished, **confirm that the curl commands fetch the latest version above**.
109115
4. Update the `MinimumVersion` constant in the [src-cli package](https://github.com/sourcegraph/sourcegraph/tree/master/internal/src-cli/consts.go).
110116

111-
**Note**: The version recommended by a Sourcegraph instance will be the highest patch version with the same major and minor version as the set minimum. This means that 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.
117+
### Patch releases
118+
119+
If a backwards-compatible change is made _after_ a backwards-incompatible one, the backwards-compatible one should be re-released to older instances that support it.
120+
121+
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.
122+
123+
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 and re-releases with a new patch version.
124+
125+
For example, suppose we have the the recommended versions.
126+
127+
| Sourcegraph version | Recommended src-cli version |
128+
| ------------------- | --------------------------- |
129+
| `3.100` | `3.90.5` |
130+
| `3.99` | `3.85.7` |
131+
132+
If a new feature is added to a new `3.91.6` release of src-cli and this change requires only features available in Sourcegraph `3.99`, then this feature should also be present in a new `3.85.8` release of src-cli. Because a Sourcegraph instance will automatically select the highest patch version, all non-breaking changes should increment only the patch version.
133+
134+
Note that if instead the recommended src-cli version for Sourcegraph `3.99` was `3.90.4` in the example above, there is no additional step required, and the new patch version of src-cli will be available to both Sourcegraph versions.

0 commit comments

Comments
 (0)