This document is a guide intended for folks interested in contributing to opslevel-cli. Below, we document the process by which members of the community should create issues and submit pull requests (PRs) in this repository. This guide assumes you are using macOS and are comfortable with the command line.
If you're new to Golang development or contributing to open-source software, we encourage you to read this document from start to finish.
This project is what it is today because community members like you have opened issues, provided feedback, and contributed to the knowledge loop for the entire community. Whether you are a seasoned open source contributor or a first-time committer, we welcome and encourage you to contribute code, documentation, ideas, or problem statements to this project.
If you have an idea for a new feature or if you've discovered a bug, the first step is to open an issue. Please check the list of open issues before creating a new one. If you find a relevant issue, please add a comment to the open issue instead of creating a new one.
Note: All community-contributed Pull Requests must be associated with an open issue. If you submit a Pull Request that does not pertain to an open issue, you will be asked to create an issue describing the problem before the Pull Request can be reviewed.
If an issue is appropriately well scoped and describes a beneficial change to the codebase, then anyone may submit a Pull Request to implement the functionality described in the issue. See the sections below on how to do this.
The maintainers will add a good first issue label if an issue is suitable for a first-time contributor. This label often means that the required code change is small or a net-new addition that does not impact existing functionality. You can see the list of currently open issues on the Contribute page.
You will need git in order to download and modify the source code. On macOS, the best way to download git is to just install Xcode.
If you are not a member of the OpsLevel GitHub organization, you can contribute by forking the repository. For a detailed overview on forking, check out the GitHub docs on forking. In short, you will need to:
- fork the repository
- clone your fork locally
- check out a new branch for your proposed changes
- push changes to your fork
- open a pull request from your forked repository
If you are a member of the OpsLevel GitHub organization, you will have push access to the repo. Rather than forking to make your changes, just clone the repository, check out a new branch, and push directly to that branch.
First make sure you have working golang development environment setup.
You will also need an OpsLevel API Token from your account to successfully make API calls against. Once you have the API token it is best to put it in your terminal's environment
export OPSLEVEL_API_TOKEN=XXXXXXXXXYou can run your local code as if it was a prebuilt CLI using:
go run main.go -hThis way you can iterate on the CLI code quickly to test out your new functionality.
To test local code against a feature branch in the opslevel-go repository, run:
# initializes opslevel-go submodule then sets up src/go.work
task workspace
# git checkouts my-feature-branch in the src/submodules/opslevel-go directory
git -C ./src/submodules/opslevel-go checkout --track origin/my-feature-branchCode imported from github.com/opslevel/opslevel-go will now be sourced from the
local my-feature-branch.
Before submitting the pull request, you need add a change entry via Changie so that your contribution changes can be tracked for our next release.
To install Changie, follow the directions here.
Next, to create a new change entry, in the root of the repository run: changie new
Follow the prompts to create your change entry - remember this is what will show up in the changelog. Changie registers the change in a .yaml file, and that file must be included in your pull request before we can release.
OpsLevel provides a CI environment to test changes through GitHub Actions. For example, if you submit a pull request to the repo, GitHub will trigger automated code checks and tests upon approval from an OpsLevel maintainer.
A maintainer will review your PR. They may suggest code revision for style or clarity, or request that you add unit or integration test(s). These are good things! We believe that, with a little bit of help, anyone can contribute high-quality code.
- First time contributors should be aware that code checks + unit tests require a maintainer to approve.
Once all tests are passing and your PR has been approved, a maintainer will merge your changes into the active development branch. And that's it! It will be available in the next release that is cut. Happy developing 🎉