Skip to content

Latest commit

 

History

History
153 lines (95 loc) · 4.44 KB

CONTRIBUTING.md

File metadata and controls

153 lines (95 loc) · 4.44 KB
Raw

Contributing

Getting Started

This is a single top-level namespace filled with packages. Each directory is potentially a package. Binary builds are done on packages with a main subpackage.

Install Golang

Using asdf-vm

We utilize a .go-version file that can be used by asdf-vm like so:

cd /path/to/sopstool/repository/
asdf plugin add golang
asdf install golang

Using goenv

goenv will prefer the GOENV_VERSION environment variable first before looking for the .go-version file when determining which Golang version to install. If you do not have this set (echo $GOENV_VERSION is empty), install like so:

cd /path/to/sopstool/repository/
goenv install

Using gimme

gimme uses eval in a simple way:

eval "$(gimme 1.17)"

From the developers

You can download and install the Golang directly from the website.

Additional Go Libraries

Install gomock

go get -u github.com/golang/mock/gomock && go install github.com/golang/mock/mockgen

Install golangci-lint

brew tap golangci/tap
brew install golangci/tap/golangci-lint

Build

With Go 1.11+ and addition of Modules, Go projects can be located outside the $GOPATH.

If you are having issues, review the FAQ.

If generate has already run, then it does not need to run again.

go build
go fmt ./...

Unit Tests

Each module is unit tested, and passes all tests.

go test ./...

Linting

golangci-lint runs several popular Go linters quickly:

golangci-lint run

Releasing

This project uses GoReleaser for builds and releases. Doing the tag/release below triggers the appropriate actions.

  1. Preview the release (optional)

    You can preview the package changes by running scripts/release-preview. This will show a summary of changes since the last release.

  2. Prepare the release:

    git checkout master && git pull

    Commit and tag with the intended version bump:

    git commit -am "Tagging release $VERSION" && git tag v$VERSION

    For example:

    git commit -am "Tagging release 0.1.1" && git tag v0.1.1

    Then push the tag and commit to Github:

    git push && git push --tags # or git push --follow-tags but YMMV

  3. Watch for the release to pass CI. CI publishes the release and pushes the artifacts.

Versioning

We use Semantic Versioning (2.0) for numbering our releases.

Summary: Given a version number MAJOR.MINOR.PATCH, increment the:

  1. MAJOR (first) version when you make incompatible API changes
  2. MINOR (second) version when you add functionality in a backwards-compatible manner
  3. PATCH (third) version when you make backwards-compatible bug fixes or internal changes
  4. In general, don't manually increment prerelease versions - we typically use that for automatic per-build numbering

Patterns

Godownloader

We used to use godownloader to generate the installer scripts. This is deprecated now, but the majority of the scripts used have not changed in a while. Any fixes will need to be by-hand.

Common third-party modules in use

  • cobra
  • yaml
  • mock

Errors

TODO

Tests

Write tests for all your public APIs. It can also be useful to write unit tests for private APIs if the methods are complex. Use mocks intelligently. Remember to properly handle and return promises and other async code to avoid those tests getting missed. Don't check in tests with the 'only' flag.

Documentation

Document all public APIs to help users understand the module at a glance. Also consider documenting private APIs, especially as the methods become less obvious and the documentation can help future maintainers.

Style

Clean up style warnings thrown by gofmt/golangci-lint (configured at the base of this repository in .golangci.yml). These will be marked as build failures in CI. Also consider using these tools to automatically clean up your code style while conforming to the configuration.