Skip to content

Commit 83f068a

Browse files
rocktaviousrocktavious
authored
overhaul contributing based on feedback from evan (#393)
* overhaul contributing based on feedback from evan * more fixes after personal review * Apply suggestions from code review * Apply suggestions from code review
1 parent 814b7cd commit 83f068a

1 file changed

Lines changed: 132 additions & 54 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 132 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -1,104 +1,182 @@
1-
# Contributing
1+
# Contributing to opslevel-cli
22

3-
1. [About this document](#about-this-document)
4-
1. [Getting the code](#getting-the-code)
5-
1. [Local development](#local-development)
6-
1. [Submitting a Pull Request](#submitting-a-pull-request)
3+
👋 Welcome, and thank you for your interest in contributing to `opslevel-cli`! This guide will help you ramp up, propose changes, develop locally, and contribute code effectively.
74

8-
## About this document
5+
---
96

10-
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.
7+
## Table of Contents
118

12-
If you're new to Golang development or contributing to open-source software, we encourage you to read this document from start to finish.
9+
1. [About the CLI](#about-the-cli)
10+
2. [Getting Started](#getting-started)
11+
3. [Development Workflow](#development-workflow)
12+
4. [Proposing and Submitting Changes](#proposing-and-submitting-changes)
13+
5. [Command Architecture & Style](#command-architecture--style)
14+
6. [Testing & Tooling](#testing--tooling)
15+
7. [Release Process](#release-process)
1316

14-
## Proposing a change
17+
---
1518

16-
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.
19+
## About the CLI
1720

18-
### Defining the problem
21+
The `opslevel-cli` is a command-line interface for interacting with the [OpsLevel](https://www.opslevel.com) API. It helps engineers automate, inspect, and manage their service catalog, ownership, checks, and more.
1922

20-
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](https://github.com/OpsLevel/cli/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.
23+
### Architecture
2124

22-
> **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.
25+
**[Cobra](https://github.com/spf13/cobra)** is the library we use to define our CLI. Commands are defined as Go structs with handlers, descriptions, and flags.
26+
- **[Viper](https://github.com/spf13/viper)** handles flag parsing, environment variables, and configuration files. Examples of our usage of it are [here](https://github.com/OpsLevel/cli/blob/main/src/cmd/root.go#L44) and [here](https://github.com/OpsLevel/cli/blob/main/src/cmd/policy.go#L246)
27+
- Modular command files live under `/cmd`, grouped by functionality (e.g., services, checks, etc.).
28+
- Commands are registered to `rootCmd` via `init()` functions.
29+
- 80% of our functionality is provided by opslevel-go and the purpose of this CLI is just to marshal data between the user and opslevel-go in a UX friendly way.
30+
- Most commands follow the standard CRUD pattern `opslevel create ...`, `opslevel get ...`, `opslevel list ...`, `opslevel update ...`, `opslevel delete ...`, etc.
31+
- We have an `opslevel beta` subcommand for experimental commands that are subject to change.
2332

24-
### Submitting a change
33+
---
2534

26-
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.
35+
## Getting Started
2736

28-
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](https://github.com/OpsLevel/cli/contribute) page.
37+
### Clone the Repo
2938

30-
## Getting the code
39+
If you're an external contributor fork the repo, then:
3140

32-
### Installing git
33-
34-
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](https://developer.apple.com/support/xcode/).
41+
```bash
42+
git clone https://github.com/YOUR_USERNAME/cli.git
43+
cd cli
44+
git checkout -b my-feature
45+
```
3546

36-
### External contributors
47+
If you're part of the OpsLevel org:
3748

38-
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](https://help.github.com/en/articles/fork-a-repo). In short, you will need to:
49+
```bash
50+
git clone git@github.com:OpsLevel/cli.git
51+
cd cli
52+
git checkout -b my-feature
53+
```
3954

40-
1. fork the repository
41-
2. clone your fork locally
42-
3. check out a new branch for your proposed changes
43-
4. push changes to your fork
44-
5. open a pull request from your forked repository
55+
> You might need to be given permissions to the repo, please reach out to team platform.
4556
46-
### OpsLevel contributors
57+
### Prerequisites
4758

48-
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.
59+
- [Task](https://taskfile.dev)
60+
- An [OpsLevel API Token](https://app.opslevel.com/api_tokens)
4961

50-
## Local Development
62+
You can use `task setup` to run an idempotent one-time setup.
5163

52-
### Installation
64+
Set your API token:
5365

54-
First make sure you have working [golang development environment](https://learn.gopherguides.com/courses/preparing-your-environment-for-go-development) setup.
66+
```sh
67+
export OPSLEVEL_API_TOKEN=your_token_here
68+
```
5569

56-
You will also need an [OpsLevel API Token](https://app.opslevel.com/api_tokens) 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
70+
If you need to target a different environment, set the `OPSLEVEL_API_URL` environment variable:
5771

5872
```sh
59-
export OPSLEVEL_API_TOKEN=XXXXXXXXX
73+
export OPSLEVEL_API_URL=https://self-hosted.opslevel.dev/
6074
```
6175

62-
### Local Development Testing
76+
---
77+
78+
## Development Workflow
6379

64-
You can run your local code as if it was a prebuilt CLI using:
80+
### Run the CLI Locally
6581

6682
```sh
67-
go run main.go -h
83+
cd ./src
84+
go run main.go --help
6885
```
6986

70-
This way you can iterate on the CLI code quickly to test out your new functionality.
87+
This is the easiest way to test your changes live.
7188

72-
#### Local Development with an `opslevel-go` Feature Branch
89+
### Using a commit from an `opslevel-go` Branch
7390

74-
To test local code against a feature branch in the `opslevel-go` repository, run:
91+
Sometimes you will need to make CLI changes in tandem with changes to [`opslevel-go`](https://github.com/OpsLevel/opslevel-go).
92+
To test changes from a local branch of [`opslevel-go`](https://github.com/OpsLevel/opslevel-go):
7593

7694
```sh
77-
# initializes opslevel-go submodule then sets up src/go.work
95+
# Set up workspace using task
7896
task workspace
7997

80-
# git checkouts my-feature-branch in the src/submodules/opslevel-go directory
98+
# Switch to your feature branch in the submodule
8199
git -C ./src/submodules/opslevel-go checkout --track origin/my-feature-branch
82100
```
83101

84-
Code imported from `github.com/opslevel/opslevel-go` will now be sourced from the
85-
local `my-feature-branch`.
102+
All CLI calls will now use your local `opslevel-go` code checked out into the submodule at `./src/submodules/opslevel-go`.
103+
This way you can effectively work on both the CLI and `opslevel-go` in parallel if needed.
104+
105+
## Testing & Tooling
106+
107+
- Use `task test` to run tests locally
108+
- Use `task lint` to check for code quality issues locally
109+
- Use `task fix` to fix formatting, linting, go.mod, and update submodule all in one go
110+
111+
Our CI pipeline will run `task ci` which can also be run locally to debug any issue that might only arise in CI.
112+
113+
---
114+
115+
## Proposing and Submitting Changes
116+
117+
### 1. Open an Issue
86118

87-
### Changie (Change log generation)
119+
If you're fixing a bug or adding a feature, please [open an issue](https://github.com/OpsLevel/cli/issues) first. This helps us track discussions and ensures your work aligns with project goals.
88120

89-
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.
121+
> **Note:** All PRs must be tied to a GitHub issue.
90122
91-
To install Changie, follow the directions [here](https://changie.dev/guide/installation/).
123+
Look for issues marked `good first issue` if you're new.
124+
125+
### 2. Submit a Pull Request
126+
127+
- Push your changes to your fork or feature branch
128+
- Run `changie new` to create a changelog entry
129+
- Open a PR to `main` or the relevant feature branch
130+
- Our GitHub Actions pipeline will run tests and lint checks
131+
- A maintainer will review your PR and request changes if needed
132+
133+
Once approved and merged, your change will be included in the next release.
134+
135+
---
136+
137+
## Command Architecture & Style
138+
139+
- Each CLI command lives in its own file under `/cmd`
140+
- Commands should:
141+
- Register themselves via `init()`
142+
- Use `RunE` instead of `Run` for error handling
143+
- Flags and environment variables should be registered with Viper for consistency
144+
- Prefer readable, minimalistic command logic — delegate heavy logic to opslevel-go unless it's not possible
145+
146+
### Minimal Command Example
147+
148+
The following shows the minimum amount of code needed to create a command. There are a plethora of commands already registered to the root command, so this is just an example of how to create a new command.
149+
Please take a look at the existing commands to get a feel for how they work and whats possible.
150+
151+
```go
152+
var exampleCmd = &cobra.Command{
153+
Use: "example",
154+
Short: "Hello World Command",
155+
Long: "Hello World Command to show how an example command works",
156+
RunE: func(cmd *cobra.Command, args []string) error {
157+
log.Info().Msg("Hello World!")
158+
return nil
159+
},
160+
}
161+
162+
func init() {
163+
rootCmd.AddCommand(exampleCmd)
164+
}
165+
```
92166

93-
Next, to create a new change entry, in the root of the repository run: `changie new`
167+
---
94168

95-
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.
169+
## Release Process
96170

97-
## Submitting a Pull Request
171+
- All customer facing changes must have a [Changie](https://changie.dev) changelog entry
172+
- Run: `changie new`
173+
- Follow prompts to categorize your change
174+
- This generates a YAML file in `.changes/` that must be committed with your PR
98175

99-
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.
176+
- CI/CD (GitHub Actions) runs lint and tests automatically on pull requests and the main branch
177+
- Maintainers will merge once approved
178+
- Your contribution will be included in the next versioned release (triggered by a maintainer)
100179

101-
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.
102-
- First time contributors should be aware that code checks + unit tests require a maintainer to approve.
180+
---
103181

104-
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 :tada:
182+
Happy hacking 🎉 and thank you for helping improve the `opslevel-cli`!

0 commit comments

Comments
 (0)