chore: updates to contributing docs and tooling (#4418)

runatlantis · Apr 30, 2024 · 3f87f7b · 3f87f7b
1 parent 92ffffb
commit 3f87f7b
Show file tree

Hide file tree

Showing 2 changed files with 78 additions and 62 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,9 +1,24 @@
-# Topics
-* [Reporting Issues](#reporting-issues)
-* [Reporting Security Issues](#reporting-security-issues)
-* [Updating The Website](#updating-the-website)
-* [Developing](#developing)
-* [Releasing](#creating-a-new-release)
+# Contributing <!-- omit in toc -->
+
+# Table of Contents <!-- omit in toc -->
+- [Reporting Issues](#reporting-issues)
+- [Reporting Security Issues](#reporting-security-issues)
+- [Updating The Website](#updating-the-website)
+- [Developing](#developing)
+  - [Running Atlantis Locally](#running-atlantis-locally)
+  - [Running Atlantis With Local Changes](#running-atlantis-with-local-changes)
+    - [Rebuilding](#rebuilding)
+  - [Running Tests Locally](#running-tests-locally)
+  - [Running Tests In Docker](#running-tests-in-docker)
+  - [Calling Your Local Atlantis From GitHub](#calling-your-local-atlantis-from-github)
+  - [Code Style](#code-style)
+    - [Logging](#logging)
+    - [Errors](#errors)
+    - [Testing](#testing)
+    - [Mocks](#mocks)
+- [Backporting Fixes](#backporting-fixes)
+  - [Manual Backporting Fixes](#manual-backporting-fixes)
+- [Creating a New Release](#creating-a-new-release)
 
 # Reporting Issues
 * When reporting issues, please include the output of `atlantis version`.
@@ -23,11 +38,11 @@ open your browser to http://localhost:8080.
 ## Running Atlantis Locally
 * Clone the repo from https://github.com/runatlantis/atlantis/
 * Compile Atlantis:
-    ```
+    ```sh
     go install
     ```
 * Run Atlantis:
-    ```
+    ```sh
     atlantis server --gh-user <your username> --gh-token <your token> --repo-allowlist <your repo> --gh-webhook-secret <your webhook secret> --log-level debug
     ```
     If you get an error like `command not found: atlantis`, ensure that `$GOPATH/bin` is in your `$PATH`.
@@ -36,62 +51,66 @@ open your browser to http://localhost:8080.
 Docker compose is set up to start an atlantis container and ngrok container in the same network in order to expose the atlantis instance to the internet.  In order to do this, create a file in the repository called `atlantis.env` and add the required env vars for the atlantis server configuration.
 
 e.g.
-```
+
+```sh
+NGROK_AUTH=1234567890
+
 ATLANTIS_GH_APP_ID=123
 ATLANTIS_GH_APP_KEY_FILE="/.ssh/somekey.pem"
 ATLANTIS_GH_WEBHOOK_SECRET=12345
 ```
 
-Note: `~/.ssh` is mounted to allow for referencing any local ssh keys
+Note: `~/.ssh` is mounted to allow for referencing any local ssh keys.
 
 Following this just run:
 
-```
+```sh
 make build-service
-docker-compose up
+docker-compose up --detach
+docker-compose logs --follow
 ```
 
 ### Rebuilding
-
 If the ngrok container is restarted, the url will change which is a hassle. Fortunately, when we make a code change, we can rebuild and restart the atlantis container easily without disrupting ngrok.
 
 e.g.
 
-```
+```sh
 make build-service
 docker-compose up --detach --build
 ```
 
-## Running Tests Locally:
-
+## Running Tests Locally
 `make test`. If you want to run the integration tests that actually run real `terraform` commands, run `make test-all`.
 
-## Running Tests In Docker:
-```
+## Running Tests In Docker
+```sh
 docker run --rm -v $(pwd):/go/src/github.com/runatlantis/atlantis -w /go/src/github.com/runatlantis/atlantis ghcr.io/runatlantis/testing-env:latest make test
 ```
 
 Or to run the integration tests
-```
+
+```sh
 docker run --rm -v $(pwd):/go/src/github.com/runatlantis/atlantis -w /go/src/github.com/runatlantis/atlantis ghcr.io/runatlantis/testing-env:latest make test-all
 ```
 
 ## Calling Your Local Atlantis From GitHub
 - Create a test terraform repository in your GitHub.
 - Create a personal access token for Atlantis. See [Create a GitHub token](https://github.com/runatlantis/atlantis/tree/main/runatlantis.io/docs/access-credentials.md#generating-an-access-token).
 - Start Atlantis in server mode using that token:
-```
+```sh
 atlantis server --gh-user <your username> --gh-token <your token> --repo-allowlist <your repo> --gh-webhook-secret <your webhook secret> --log-level debug
 ```
 - Download ngrok from https://ngrok.com/download. This will enable you to expose Atlantis running on your laptop to the internet so GitHub can call it.
 - When you've downloaded and extracted ngrok, run it on port `4141`:
-```
+```sh
 ngrok http 4141
 ```
 - Create a Webhook in your repo and use the `https` url that `ngrok` printed out after running `ngrok http 4141`. Be sure to append `/events` so your webhook url looks something like `https://efce3bcd.ngrok.io/events`. See [Add GitHub Webhook](https://github.com/runatlantis/atlantis/blob/main/runatlantis.io/docs/configuring-webhooks.md#configuring-webhooks).
 - Create a pull request and type `atlantis help`. You should see the request in the `ngrok` and Atlantis logs and you should also see Atlantis comment back.
 
 ## Code Style
+
 ### Logging
 - `ctx.Log` should be available in most methods. If not, pass it down.
 - levels:
@@ -161,12 +180,11 @@ go get github.com/petergtz/pegomock/...
 ```
 
 # Backporting Fixes
-
 Atlantis now uses a [cherry-pick-bot](https://github.com/googleapis/repo-automation-bots/tree/main/packages/cherry-pick-bot) from Google. The bot assists in maintaining changes across releases branches by easily cherry-picking changes via pull requests.
 
 Maintainers and Core Contributors can add a comment to a pull request:
 
-```
+```sh
 /cherry-pick target-branch-name
 ```
 
@@ -175,7 +193,6 @@ target-branch-name is the branch to cherry-pick to. cherry-pick-bot will cherry-
 The bot will immediately try to cherry-pick a merged PR. On unmerged pull request, it will not do anything immediately, but wait until merge. You can comment multiple times on a PR for multiple release branches.
 
 ## Manual Backporting Fixes
-
 The bot will fail to cherry-pick if the feature branches' git history is not linear (merge commits instead of rebase). In that case, you will need to manually cherry-pick the squashed merged commit from main to the release branch
 
 1. Switch to the release branch intended for the fix.

diff --git a/docker-compose.yml b/docker-compose.yml
@@ -1,42 +1,41 @@
 # Note: This file is only used for Atlantis local development
-version: "3.8"
 services:
-    ngrok:
-        image: wernight/ngrok:latest@sha256:d211f29ebcfe5f4e72df4fa8bdd9a667886e127d7fcb1be4a1af5ad83a8a1b77
-        ports:
-        - 4040:4040
-        environment:
-            # https://dashboard.ngrok.com/get-started/your-authtoken
-            # NGROK_AUTH: REPLACE-WITH-YOUR-TOKEN // set this in atlantis.env
-            NGROK_PROTOCOL: http
-            NGROK_PORT: atlantis:4141
-        env_file:
-            - ./atlantis.env
-        depends_on:
-        - atlantis
-    redis:
-        image: redis:7.2-alpine@sha256:a40e29800d387e3cf9431902e1e7a362e4d819233d68ae39380532c3310091ac
-        restart: always
-        ports:
-        - '6379:6379'
-        command: redis-server --save 20 1 --loglevel warning --requirepass test123
-        volumes:
-        - redis:/data
-    atlantis:
-        depends_on:
-        - redis
-        build:
-            context: .
-            dockerfile: Dockerfile.dev
-        ports:
-        - 4141:4141
-        volumes:
-            - ~/.ssh:/.ssh
-            - ./:/atlantis/src
-        # Contains the flags that atlantis uses in env var form
-        env_file:
-            - ./atlantis.env
+  ngrok:
+    image: wernight/ngrok:latest@sha256:d211f29ebcfe5f4e72df4fa8bdd9a667886e127d7fcb1be4a1af5ad83a8a1b77
+    ports:
+      - 4040:4040
+    environment:
+      # https://dashboard.ngrok.com/get-started/your-authtoken
+      # NGROK_AUTH: REPLACE-WITH-YOUR-TOKEN // set this in atlantis.env
+      NGROK_PROTOCOL: http
+      NGROK_PORT: atlantis:4141
+    env_file:
+      - atlantis.env
+    depends_on:
+      - atlantis
+  redis:
+    image: redis:7.2-alpine@sha256:a40e29800d387e3cf9431902e1e7a362e4d819233d68ae39380532c3310091ac
+    restart: always
+    ports:
+      - 6379:6379
+    command: redis-server --save 20 1 --loglevel warning --requirepass test123
+    volumes:
+      - redis:/data
+  atlantis:
+    depends_on:
+      - redis
+    build:
+      context: .
+      dockerfile: Dockerfile.dev
+    ports:
+      - 4141:4141
+    volumes:
+      - ${HOME}/.ssh:/.ssh:ro
+      - ${PWD}:/atlantis/src:ro
+    # Contains the flags that atlantis uses in env var form
+    env_file:
+      - atlantis.env
 
 volumes:
-    redis:
-        driver: local
+  redis:
+    driver: local