Skip to content

Commit a76c764

Browse files
SgtCoDFishSgtCoDFish
committed
add a simple contributing file to help onboard new users
Signed-off-by: Ashley Davis <ashley.davis@cyberark.com>
1 parent d5013d4 commit a76c764

1 file changed

Lines changed: 243 additions & 0 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 243 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,243 @@
1+
# Contributing to Discovery Agent
2+
3+
Thank you for your interest in contributing! This document provides guidelines and instructions for contributing.
4+
5+
Note that this repository holds two separate components:
6+
7+
- disco-agent: For CyberArk DisCo
8+
- venafi-kubernetes-agent: For TLSPK / Certificate Manager SaaS
9+
10+
## Table of Contents
11+
12+
- [Getting Started](#getting-started)
13+
- [Development Environment](#development-environment)
14+
- [Making Changes](#making-changes)
15+
- [Testing](#testing)
16+
- [Submitting a Pull Request](#submitting-a-pull-request)
17+
- [Code Review Process](#code-review-process)
18+
- [Additional Resources](#additional-resources)
19+
20+
### Prerequisites
21+
22+
Before you begin, ensure you have the following installed:
23+
24+
- [Go](https://golang.org/doc/install) (version specified in `go.mod`)
25+
- [Make](https://www.gnu.org/software/make/)
26+
- [Git](https://git-scm.com/)
27+
- [Docker](https://docs.docker.com/get-docker/) (for building container images)
28+
29+
To check which Go version will be used:
30+
31+
```bash
32+
make which-go
33+
```
34+
35+
It's also possible to use a vendored version of Go, via `make vendor-go`.
36+
37+
### Repository Tooling
38+
39+
Most of the setup logic for provisioning tooling and for handling builds and testing
40+
is defined in Makefile logic.
41+
42+
Specifically, `the make/_shared` directory contains shared Makefile logic derived from
43+
the cert-manager [makefile-modules](https://github.com/cert-manager/makefile-modules/) project.
44+
45+
### Setting Up Your Development Environment
46+
47+
1. **Fork the repository** on GitHub
48+
49+
2. **Clone your fork:**
50+
51+
```bash
52+
git clone git@github.com:YOUR-USERNAME/jetstack-secure.git
53+
cd jetstack-secure
54+
```
55+
56+
3. **Add the upstream remote:**
57+
58+
```bash
59+
git remote add upstream git@github.com:jetstack/jetstack-secure.git
60+
```
61+
62+
4. **Run initial verification:**
63+
64+
```bash
65+
make verify
66+
```
67+
68+
This ensures your environment is set up correctly.
69+
70+
## Development Environment
71+
72+
### Local Execution
73+
74+
To build and run the agent locally:
75+
76+
```bash
77+
go run main.go agent --agent-config-file ./path/to/agent/config/file.yaml -p 0h1m0s
78+
```
79+
80+
Example configuration files are available:
81+
- [agent.yaml](./agent.yaml)
82+
- [examples/one-shot-secret.yaml](./examples/one-shot-secret.yaml)
83+
- [examples/cert-manager-agent.yaml](./examples/cert-manager-agent.yaml)
84+
85+
You can also run a local echo server to monitor agent requests:
86+
87+
```bash
88+
go run main.go echo
89+
```
90+
91+
### Useful Make Targets
92+
93+
- `make help` - Show all available make targets
94+
- `make verify` - Run all verification checks (linting, formatting, etc.)
95+
- `make test-unit` - Run unit tests
96+
- `make test-helm` - Run Helm chart tests
97+
- `make generate` - Generate code, documentation, and other artifacts
98+
- `make oci-build-preflight` - Build container image
99+
- `make clean` - Clean all temporary files
100+
101+
## Making Changes
102+
103+
### Creating a Branch
104+
105+
Always create a new branch for your changes:
106+
107+
```bash
108+
git checkout -b feature/your-feature-name
109+
```
110+
111+
Use descriptive branch names:
112+
- `feature/` for new features
113+
- `fix/` for bug fixes
114+
- `docs/` for documentation changes
115+
- `refactor/` for refactoring
116+
117+
### Code Style
118+
119+
This project follows standard Go conventions:
120+
121+
- Run `make verify-golangci-lint` to check your code
122+
- Run `make fix-golangci-lint` to automatically fix some issues
123+
- Ensure all code is formatted with `gofmt`
124+
- Follow the [Effective Go](https://golang.org/doc/effective_go) guidelines
125+
- Most of the conventions are enforced by linters, and violations will prevent code being merged
126+
127+
### Committing Changes
128+
129+
1. **Stage your changes:**
130+
131+
```bash
132+
git add .
133+
```
134+
135+
2. **Run verification before committing:**
136+
137+
```bash
138+
make verify
139+
```
140+
141+
3. **Commit with a descriptive message:**
142+
143+
```bash
144+
git commit -m "Brief description of your changes"
145+
```
146+
147+
Write clear commit messages:
148+
- Use the imperative mood ("Add feature" not "Added feature")
149+
- Keep the first line under 72 characters
150+
- Add additional context in the body if needed
151+
152+
## Testing
153+
154+
### Running Tests Locally
155+
156+
Before submitting a PR, ensure all tests pass:
157+
158+
```bash
159+
# Run unit tests
160+
make test-unit
161+
162+
# Run Helm tests
163+
make test-helm
164+
165+
# Run all verification checks
166+
make verify
167+
```
168+
169+
### End-to-End Tests
170+
171+
E2E tests run automatically in CI when you add specific labels to your PR:
172+
173+
- Add the `test-e2e` label to trigger GKE-based E2E tests
174+
- Add the `keep-e2e-cluster` label if you need to keep the cluster for debugging (remember to delete it manually afterward to avoid costs)
175+
176+
The E2E test script is located at [hack/e2e/test.sh](./hack/e2e/test.sh).
177+
178+
### Writing Tests
179+
180+
- Add unit tests for all new functionality
181+
- Place tests in `*_test.go` files alongside the code they test
182+
- Use the [testify](https://github.com/stretchr/testify) library for assertions
183+
- Aim for meaningful test coverage, not just high percentages
184+
185+
## Submitting a Pull Request
186+
187+
1. **Push your branch to your fork:**
188+
189+
```bash
190+
git push origin feature/your-feature-name
191+
```
192+
193+
2. **Create a Pull Request** on GitHub from your fork to the `master` branch of `jetstack/jetstack-secure`
194+
195+
3. **Fill out the PR description** with:
196+
- Clear description of the changes
197+
- Related issue numbers (if applicable)
198+
- Testing instructions
199+
- Any breaking changes or special considerations
200+
201+
4. **Ensure CI passes:**
202+
- All tests must pass
203+
- Code must pass verification / linting checks
204+
- No merge conflicts
205+
206+
## Code Review Process
207+
208+
### For All Contributors
209+
210+
- PRs require approval before merging
211+
- Keep PRs focused and reasonably sized
212+
- Update your branch if `master` has moved forward:
213+
214+
```bash
215+
git fetch upstream
216+
git rebase upstream/master
217+
git push --force-with-lease origin feature/your-feature-name
218+
```
219+
220+
### For CyberArk Contributors
221+
222+
**Contributors from inside CyberArk should reach out to the cert-manager team for reviews for PRs which are passing CI.**
223+
224+
The cert-manager team maintains this project and will provide code reviews and guidance for merging changes.
225+
226+
## Additional Resources
227+
228+
- [Project Documentation](https://docs.cyberark.com/mis-saas/vaas/k8s-components/c-tlspk-agent-overview/)
229+
- [Issue Tracker](https://github.com/jetstack/jetstack-secure/issues)
230+
- [Release Process](./RELEASE.md)
231+
- [cert-manager Community](https://cert-manager.io/docs/contributing/)
232+
233+
## Getting Help
234+
235+
If you need help or have questions:
236+
237+
1. Check existing [issues](https://github.com/jetstack/jetstack-secure/issues) and [documentation](https://docs.cyberark.com/mis-saas/vaas/k8s-components/c-tlspk-agent-overview/)
238+
2. Open a new issue with the `question` label
239+
3. For CyberArk contributors, reach out to the cert-manager team
240+
241+
## License
242+
243+
By contributing, you agree that your contributions will be licensed under the license in the LICENSE file in the root directory of this repository.

0 commit comments

Comments
 (0)