Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
239 lines (166 loc) · 6.23 KB

CONTRIBUTING.md

File metadata and controls

239 lines (166 loc) · 6.23 KB
Raw

Contributing to ArgoCD Diff Preview

Thank you for your interest in contributing to ArgoCD Diff Preview! This document provides guidelines and instructions for contributing to the project.

GitHub Codespaces (Simplest way to get started)

  1. Open the repository in GitHub Codespaces:

  1. Verify the setup works:
make run-with-go target_branch=helm-example-3

Output should look similar to like this:

Important

If you experience issues with the setup, please open an issue in the repository! 🚀

Local Development Environment Setup

Prerequisites

Required:

  • Go (1.21+)
  • Docker
  • Git
  • Make

Required only when running with Go (not needed for Docker):

Setup

  1. Clone the repository:

    git clone https://github.com/dag-andersen/argocd-diff-preview.git
cd argocd-diff-preview

  2. Install Go dependencies:

    go mod download

  3. (Optional) Setup for documentation development:

    python3 -m venv venv
source venv/bin/activate
pip3 install mkdocs-material

Project Structure

argocd-diff-preview/
├── cmd/                  # Main application entry points
├── pkg/                  # Core application logic
├── integration-test/     # Integration tests and expected outputs
├── docs/                 # Documentation
├── argocd-config/        # Argo CD configuraiton that is installed with Argo CD
└── examples/             # Examples used by the integration tests and pull request examples

Building the tool

Building the tool with Go

make go-build

This will create a binary in the bin/ directory.

Building the tool with Docker

make docker-build

Running the tool locally

There are two ways to run the tool locally:

Using branches from the ArgoCD Diff Preview repository

make run-with-go target_branch=<your-branch-name>

or

make run-with-docker target_branch=<your-branch-name>

example to make sure the tool works run:

make run-with-go target_branch=helm-example-3

Using branches from your own fork

make run-with-go target_branch=<your-branch-name> github_org=<your-username>
make run-with-docker target_branch=<your-branch-name> github_org=<your-username>

Testing

ArgoCD Diff Preview uses integration tests to verify functionality. These tests create ephemeral Kubernetes clusters and test the application against various test scenarios.

Running Unit Tests

To run all unit tests in the project:

make run-unit-tests

Running All Integration Tests

Note

Some users have reported issues running the integration tests locally due to file permissions. If you experience any problems, we recommend using the GitHub Codespaces setup. See #255 for details.

Using Go:

make run-integration-tests-go

Using Docker:

make run-integration-tests-docker

Running a Single Integration Test

Useful for debugging specific test cases. Reuses existing cluster if available:

cd integration-test && TEST_CASE="branch-1/target-1" go test -v -timeout 10m -run TestSingleCase ./...

With Docker:

cd integration-test && TEST_CASE="branch-1/target-1" go test -v -timeout 10m -run TestSingleCase -docker ./...

Force all tests to use the ArgoCD API instead of CLI:

cd integration-test && go test -v -timeout 60m -run TestIntegration -use-argocd-api ./...

Updating Expected Outputs

If you have made changes to the output of the tool, you can update the expected output files:

make update-integration-tests          # Update with Go binary
make update-integration-tests-docker   # Update with Docker

This will update the output files in the integration-test/ directory.

Tip

Before you create a pull request, please run make check-release to verify that the tool works as expected. This runs linting, unit tests, and integration tests. Feel free to reach out if you need help! 🚀

Documentation

The project uses MkDocs for documentation. To serve the documentation locally:

make mkdocs

This will open the documentation in your default browser.

Illustrations

For most documentation, standard markdown code blocks are sufficient:

```yaml
apiVersion: v1
kind: ConfigMap
```

Only use the tools below when a plain code block isn't enough - for example, when you need to create a diagram explaining a concept.

Tool Use case
Carbon When you need a code block as an png
Affinity Any illustration/diagram where a code block isn't enough

Code (Carbon)

When you need an illustration including a code snippet. E.g., when you want to draw on top of a code block.

  1. Open Carbon
  2. Import settings from docs/assets/carbon-config.json
  3. Export as PNG

Advanced Illustrations

For any visual that can't be expressed as a code block, we use Affinity.

File conventions:

  • Store both source (.af) and export (.png) in docs/assets/
  • Name them identically: appset-patching.af → appset-patching.png
  • One illustration per file

Why not use draw.io or similar? Tools made with tools like draw.io tend to look ugly, and they are overall less powerful.

License

By contributing to ArgoCD Diff Preview, you agree that your contributions will be licensed under the project's license (refer to the LICENSE file in the repository).