From 34211715da8611ef380cd5eb5ddfca3985ba0712 Mon Sep 17 00:00:00 2001 From: nick-hollingsworth-hs Date: Thu, 26 Oct 2017 14:33:01 -0700 Subject: [PATCH 1/5] Update README with steps to start local development --- README.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/README.md b/README.md index 77e023738..91430f909 100644 --- a/README.md +++ b/README.md @@ -414,6 +414,21 @@ able to use `session_name = "${var.atlantis_user}"`. However, the backend assume role is only used for state-related API actions. Any other API actions will be performed using the assumed role specified in the `aws` provider and will have the session named as the GitHub user. +## Developing + +Follow these steps to get your local dev envrionment set up! +Make sure you have `ngrok` installed and `/Users//go/bin` is in your `$PATH`. + +1. Create your own terraform repo, ex. https://github.com/hootsuite/atlantis-example +2. `ngrok http 4141` to open your 4141 port to an URL +3. [Create a GitHub token](#create-a-github-token) for your GitHub account +4. [Add GitHub Webhook](#add-github-webhook) for your terraform repo, `$URL` will be the URL ngrok provides +5. `go install` in the atlantis directory +6. `atalntis server --gh-user $USERNAME --gh-token $TOKEN --log-level debug` to start atlantis on your machine +7. Now you can create pull requests and test atlantis out! + +Want to contribute? Check out [CONTRIBUTING](https://github.com/hootsuite/atlantis/blob/master/CONTRIBUTING.md). + ## Glossary #### Project A Terraform project. Multiple projects can be in a single GitHub repo. From 09960deea360ae26377473dac935a15c9e8deced Mon Sep 17 00:00:00 2001 From: nicholas-wu-hs Date: Sat, 28 Oct 2017 23:39:47 -0700 Subject: [PATCH 2/5] Move developing section from README.md to CONTRIBUTING.md --- CONTRIBUTING.md | 37 +++++++++++++++++++++++++++++++++++++ README.md | 17 ++--------------- 2 files changed, 39 insertions(+), 15 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fde12cabc..ea9fa0876 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,40 @@ +# Developing + +## Running Atlantis Locally +- Get the source code: +``` +go get github.com/hootsuite/atlantis +``` +This will clone Atlantis into `$GOPATH/src/github.com/hootsuite/atlantis` (where `$GOPATH` defaults to `~/go`). +- Go to that directory: +``` +cd $GOPATH/src/github.com/hootsuite/atlantis +``` +- Compile Atlantis: +``` +go install +``` +- Run Atlantis: +``` +atlantis server --gh-user --gh-token --log-level debug +``` +If you get an error like `command not found: atlantis`, ensure that `$GOPATH/bin` is in your `$PATH`. + +## 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/hootsuite/atlantis#create-a-github-token). +- Start Atlantis in server mode using that token: +``` +atlantis server --gh-user --gh-token --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`: +``` +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/hootsuite/atlantis#add-github-webhook). +- 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 diff --git a/README.md b/README.md index 91430f909..93361d61f 100644 --- a/README.md +++ b/README.md @@ -414,21 +414,6 @@ able to use `session_name = "${var.atlantis_user}"`. However, the backend assume role is only used for state-related API actions. Any other API actions will be performed using the assumed role specified in the `aws` provider and will have the session named as the GitHub user. -## Developing - -Follow these steps to get your local dev envrionment set up! -Make sure you have `ngrok` installed and `/Users//go/bin` is in your `$PATH`. - -1. Create your own terraform repo, ex. https://github.com/hootsuite/atlantis-example -2. `ngrok http 4141` to open your 4141 port to an URL -3. [Create a GitHub token](#create-a-github-token) for your GitHub account -4. [Add GitHub Webhook](#add-github-webhook) for your terraform repo, `$URL` will be the URL ngrok provides -5. `go install` in the atlantis directory -6. `atalntis server --gh-user $USERNAME --gh-token $TOKEN --log-level debug` to start atlantis on your machine -7. Now you can create pull requests and test atlantis out! - -Want to contribute? Check out [CONTRIBUTING](https://github.com/hootsuite/atlantis/blob/master/CONTRIBUTING.md). - ## Glossary #### Project A Terraform project. Multiple projects can be in a single GitHub repo. @@ -461,6 +446,8 @@ However, if you were to lose the data, all you would need to do is run `atlantis A: Atlantis currently only supports HTTP. In order to add SSL you will need to front Atlantis server with NGINX or HAProxy. Follow the document [here](./docs/nginx-ssl-proxy.md) to use configure NGINX with SSL as a reverse proxy. +## Contributing +Want to contribute? Check out [CONTRIBUTING](https://github.com/hootsuite/atlantis/blob/master/CONTRIBUTING.md). ## Credits * Atlantis Logo: Icon made by [freepik](https://www.flaticon.com/authors/freepik) from www.flaticon.com From aa0b5b3947c476589d8658591b36d0a64327fdce Mon Sep 17 00:00:00 2001 From: nicholas-wu-hs Date: Sat, 28 Oct 2017 23:53:19 -0700 Subject: [PATCH 3/5] Update README ToC to include Contributing and other subsections --- README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/README.md b/README.md index 93361d61f..2121f22a3 100644 --- a/README.md +++ b/README.md @@ -24,13 +24,23 @@ Read about [Why We Built Atlantis](https://www.atlantis.run/blog/atlantis-releas * [Locking](#locking) * [Approvals](#approvals) * [Production-Ready Deployment](#production-ready-deployment) + * [Install Terraform](#install-terraform) + * [Hosting Atlantis](#hosting-atlantis) + * [Add GitHub Webhook](#add-github-webhook) + * [Create a GitHub Token](#create-a-github-token) + * [Start Atlantis](#start-atlantis) * [Docker](#docker) + * [Testing Out Atlantis](#testing-out-atlantis) * [Server Configuration](#server-configuration) * [AWS Credentials](#aws-credentials) + * [Multiple AWS Accounts](#multiple-aws-accounts) + * [Assume Role Session Names](#assume-role-session-names) * [Glossary](#glossary) * [Project](#project) * [Environment](#environment) * [FAQ](#faq) +* [Contributing](#contributing) +* [Credits](#credits) ## Features ➜ Collaborate on Terraform with your team From 0f8514e24e09653053cb8ce5ce04f3ef0d5de3dc Mon Sep 17 00:00:00 2001 From: nicholas-wu-hs Date: Sun, 29 Oct 2017 12:07:01 -0700 Subject: [PATCH 4/5] Remove subheadings in README ToC --- README.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/README.md b/README.md index 2121f22a3..bb46c8fdf 100644 --- a/README.md +++ b/README.md @@ -24,17 +24,9 @@ Read about [Why We Built Atlantis](https://www.atlantis.run/blog/atlantis-releas * [Locking](#locking) * [Approvals](#approvals) * [Production-Ready Deployment](#production-ready-deployment) - * [Install Terraform](#install-terraform) - * [Hosting Atlantis](#hosting-atlantis) - * [Add GitHub Webhook](#add-github-webhook) - * [Create a GitHub Token](#create-a-github-token) - * [Start Atlantis](#start-atlantis) * [Docker](#docker) - * [Testing Out Atlantis](#testing-out-atlantis) * [Server Configuration](#server-configuration) * [AWS Credentials](#aws-credentials) - * [Multiple AWS Accounts](#multiple-aws-accounts) - * [Assume Role Session Names](#assume-role-session-names) * [Glossary](#glossary) * [Project](#project) * [Environment](#environment) From 7aed3e73aa03f61f74b0ae83d3c318faf0fefca4 Mon Sep 17 00:00:00 2001 From: nicholas-wu-hs Date: Sun, 29 Oct 2017 12:08:25 -0700 Subject: [PATCH 5/5] Move Code Style under Develpoing in CONTRIBUTING.md, remove bullets --- CONTRIBUTING.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ea9fa0876..eb8d112fe 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,20 +1,23 @@ # Developing ## Running Atlantis Locally -- Get the source code: +Get the source code: ``` go get github.com/hootsuite/atlantis ``` This will clone Atlantis into `$GOPATH/src/github.com/hootsuite/atlantis` (where `$GOPATH` defaults to `~/go`). -- Go to that directory: + +Go to that directory: ``` cd $GOPATH/src/github.com/hootsuite/atlantis ``` -- Compile Atlantis: + +Compile Atlantis: ``` go install ``` -- Run Atlantis: + +Run Atlantis: ``` atlantis server --gh-user --gh-token --log-level debug ``` @@ -35,9 +38,8 @@ 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/hootsuite/atlantis#add-github-webhook). - 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 +## Code Style +### Logging - `ctx.Log` should be available in most methods. If not, pass it down. - levels: - debug is for developers of atlantis @@ -49,7 +51,7 @@ ngrok http 4141 - **NEVER** use colons "`:`" in a log since that's used to separate error descriptions and causes - if you need to have a break in your log, either use `-` or `,` ex. `failed to clean directory, continuing regardless` -## Errors +### Errors - **ALWAYS** use lowercase unless the word requires it - **ALWAYS** use `errors.Wrap(err, "additional context...")"` instead of `fmt.Errorf("additional context: %s", err)` because it is less likely to result in mistakes and gives us the ability to trace call stacks @@ -65,7 +67,7 @@ Error: setting up workspace: running git clone: no executable "git" ``` This is easier to read and more consistent -## Testing +### Testing - place tests under `{package under test}_test` to enforce testing the external interfaces - if you need to test internally i.e. access non-exported stuff, call the file `{file under test}_internal_test.go` - use `testing_util` for easier-to-read assertions: `import . "github.com/hootsuite/atlantis/testing_util"`