| runme | ||||
|---|---|---|---|---|
|
Thank you for your interest in runme. Your contributions are highly welcome.
There are multiple ways of getting involved:
Reporting bugs is one of the best ways to contribute. Before creating a bug report, please check that an issue reporting the same problem does not already exist. If there is such an issue, you may add your information as a comment.
To report a new bug you should open an issue that summarizes the bug and set the label to "bug".
If you want to provide a fix along with your bug report: That is great! In this case please send us a pull request as described in section Contribute Code.
To request a new feature you should open an issue and summarize the desired functionality and its use case. Set the issue label to "feature".
This is an outline of what the workflow for code contributions looks like
- Check the list of open issues. Either assign an existing issue to yourself, or create a new one that you would like work on and discuss your ideas and use cases.
It is always best to discuss your plans beforehand, to ensure that your contribution is in line with our goals.
- Fork the repository on GitHub
- Create a topic branch from where you want to base your work. This is usually
main - Open a new draft pull request and outline what you will be contributing
- Make commits of logical units
- Write good commit messages
- Push your changes to a topic branch in your fork of the repository
- As you push your changes, update the pull request with new information and tasks as you complete them
- Project maintainers might comment on your work as you progress
- When you are done, remove the PR's draft status and ping the maintainers for a review
This project uses a Makefile to manage build scripts. You will need make installed to run these scripts. See Makefile for a list of possible commands and what they do.
You will need to have a go installation - ideally compatible with the project's current go version (see go.mod).
If you are using homebrew, you can install the required system modules with the following command:
brew bundle --no-lockIn order to use make, install apple developer tools.
To install required CLI tools for development:
make install/devMake sure to export the global path for Go packages into your environment. For Mac and Linux, just run:
export GOPATH="$HOME/go"
PATH="$GOPATH/bin:$PATH"This codebase is used for a few different purposes, and so there's quite a lot of architecture involved.
Following is some documentation on the different build targets runme has, and what is required to get them to build/run.
CLI is built with:
make buildThis builds the CLI binary for the current platform to an executable file "runme" in the root directory. (You can change the output with the -o flag). After this command you can access the compiled binary from the root directory in your workspace, e.g.:
./runme --version
# outputs: "runme version 1.3.0-27-g3cca8a6-3cca8a6 (3cca8a6e7d34f401c1bdd99828a7fac5b1d8fac9) on 2023-07-31T16:49:57Z"To run the server in dev mode with predictable port and TLS credentials location:
go run . server --dev --address 127.0.0.1:9999 --tls /tmp/runme/tls 2>&1WASM is built with:
make wasmThis builds the wasm file to examples/web/runme.wasm.
Like many complex go projects, this project uses a variety of linting tools to ensure code quality and prevent regressions! The main linter (revive) can be run with:
make lintThe rest of the project's linting suite can be run with:
pre-commit run --files */**Tests are run with go's default test runner. So, for example, you can run all tests with:
make testGenerate HTML representation of coverage profile
make test/coverage/htmlOutput coverage profile information for each function
make test/coverage/funcTo generate protocol buffers:
make proto/generateProtocol buffer generation is done with buf, and the buf CLI will need to be installed in order for make proto/generate to work.
Currently, we use timostamm-protobuf-ts to generate TypeScript definitions. These are uploaded to a remote buf.build registry which can be used in any npm compatible project - see the client-ts example.
Note that for protocol buffers to work with npm projects, you'll need to add the @buf registry to your npm or yarn config:
npm config set @buf:registry https://buf.build/gen/npm/v1yarn config set @buf:registry https://buf.build/gen/npm/v1While development it's not prudent to publish to the Buf's BSR (NPM etc). Instead, you can overwrite the generated types locally. Generate buffers:
make proto/generateThen overwrite buffers in the Runme extension's development project. Make sure to delete superfluous TS files to prevent bundler from stumbling.
export RUNME_EXT_BASE="../vscode-runme"
make proto/devOptionally, reset Runme extension's development project to NPM distributed buffers.
export RUNME_EXT_BASE="../vscode-runme"
make proto/dev/resetGraphQL schema are generated as part of:
make generateThis project uses genqlient to generate a GraphQL client for interacting with the Stateful API. You will need to install genqlient in order for go generate to work properly:
go install github.com/Khan/genqlientSee also the README for generating GraphQL schema from the remote endpoint, which is a pre-requisite for running go generate.
Mocks are generated as part of:
make generateThis project uses gomock to generate some mocks for some interfaces. You will need to install gomock in order for go generate to work.
The releaser uses goreleaser to handle cross-compilation, as well as snapshotting etc. This is run with:
make releaseThe requisite tools can be installed with:
make install/goreleaserAfter upgrading go to version 1.22, you'll need to make sure to reinstall dev packages, as some may be outdated:
make install/dev