docs: Contributor Guide on the Website (#4514)

Signed-off-by: Rui Chen <[email protected]>
Co-authored-by: Rui Chen <[email protected]>

.gitignore

@@ -27,6 +27,9 @@ tmp-CHANGELOG.md
 # IDE files
 *.code-workspace
 
+# draw.io backup files
+*.bkp
+
 # vuepress
 **/.vuepress/*
 !runatlantis.io/.vuepress/config.*

package.json

@@ -8,12 +8,12 @@
     "@vuepress/plugin-sitemap": "2.0.0-rc.21",
     "@vuepress/theme-default": "2.0.0-rc.21",
     "@vuepress/utils": "2.0.0-rc.9",
-    "sass-loader": "14.1.1",
-    "vue": "3.4.21",
+    "sass-loader": "14.2.1",
+    "vue": "3.4.27",
     "vuepress": "2.0.0-rc.9"
   },
   "scripts": {
-    "website:dev": "vuepress dev runatlantis.io",
+    "website:dev": "vuepress dev --host localhost runatlantis.io",
     "website:build": "NODE_OPTIONS=--openssl-legacy-provider vuepress build runatlantis.io",
     "e2e": "playwright test"
   }

runatlantis.io/.vuepress/navbar.js

@@ -2,6 +2,7 @@ const en = [
   { text: 'Home', link: '/' },
   { text: 'Guide', link: '/guide/' },
   { text: 'Docs', link: '/docs/' },
+  { text: "Contributing", link: "/contributing/" },
   { text: 'Blog', link: 'https://medium.com/runatlantis' },
 ];
 

runatlantis.io/.vuepress/sidebar.js

@@ -82,7 +82,16 @@ const en = {
               '/docs/troubleshooting-https',
           ]
       }
-  ]
+  ],
+  '/contributing/': [
+      {
+          text: 'Implementation Details',
+          children: [
+              '/contributing/events-controller',
+          ]
+      },
+      '/contributing/glossary',
+  ],
 };
 
 export default { en };

runatlantis.io/contributing/README.md

@@ -0,0 +1,14 @@
+# Atlantis Contributing Documentation
+
+These docs are for users who want to contribute to the Atlantis project. This
+can vary from writing documentation, helping the community on Slack, discussing
+issues, or writing code.
+
+:::tip Looking to get started or use Atlantis?
+If you're new, check out the [Guide](../guide/README.md) or the
+[Documentation](./../docs/README.md).
+:::
+
+### Next Steps
+
+- [Events Controller](events-controller.md)  –  How do the events work?

runatlantis.io/contributing/events-controller.md

@@ -0,0 +1,71 @@
+# Events Controller
+
+Webhooks are the primary interaction between the Version Control System (VCS)
+and Atlantis. Each VCS sends the requests to the `/events` endpoint. The
+implementation of this endpoint can be found in the
+[events_controller.go](https://github.com/runatlantis/atlantis/blob/main/server/controllers/events/events_controller.go)
+file. This file contains the Post function `func (e *VCSEventsController)
+Post(w http.ResponseWriter, r *http.Request`)` that parses the request
+according to the configured VCS.
+
+Atlantis currently handles one of the following events:
+
+- Comment Event
+- Pull Request Event
+
+All the other events are ignored.
+
+![Events Controller flow](./images/events-controller.png)
+
+## Comment Event
+
+This event is triggered whenever a user enters a comment on the Pull Request,
+Merge Request, or whatever it's called for the respective VCS. After parsing the
+VCS-specific request, the code calls the `handleCommentEvent` function, which
+then passes the processing to the `handleCommentEvent` function in the
+[command_runner.go](https://github.com/runatlantis/atlantis/blob/main/server/events/command_runner.go)
+file. This function first calls the pre-workflow hooks, then executes one of the
+below-listed commands and, at last, the post-workflow hooks.
+
+- [plan_command_runner.go](https://github.com/runatlantis/atlantis/blob/main/server/events/plan_command_runner.go)
+- [apply_command_runner.go](https://github.com/runatlantis/atlantis/blob/main/server/events/apply_command_runner.go)
+- [approve_policies_command_runner.go](https://github.com/runatlantis/atlantis/blob/main/server/events/approve_policies_command_runner.go)
+- [unlock_command_runner.go](https://github.com/runatlantis/atlantis/blob/main/server/events/unlock_command_runner.go)
+- [version_command_runner.go](https://github.com/runatlantis/atlantis/blob/main/server/events/version_command_runner.go)
+- [import_command_runner.go](https://github.com/runatlantis/atlantis/blob/main/server/events/import_command_runner.go)
+- [state_command_runner.go](https://github.com/runatlantis/atlantis/blob/main/server/events/state_command_runner.go)
+
+## Pull Request Event
+
+To handle comment events on Pull Requests, they must be created first. Atlantis
+also allows the running of commands for certain Pull Requests events.
+
+<details>
+  <summary>Pull Request Webhooks</summary>
+
+The list below links to the supported VCSs and their Pull Request Webhook
+documentation.
+
+- [Azure DevOps Pull Request Created](https://learn.microsoft.com/en-us/azure/devops/service-hooks/events?view=azure-devops#pull-request-created)
+- [BitBucket Pull Request](https://support.atlassian.com/bitbucket-cloud/docs/event-payloads/#Pull-request-events)
+- [GitHub Pull Request](https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request)
+- [GitLab Merge Request](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html#merge-request-events)
+- [Gitea Webhooks](https://docs.gitea.com/next/usage/webhooks)
+</details>
+
+The following list shows the supported events:
+
+- Opened Pull Request
+- Updated Pull Request
+- Closed Pull Request
+- Other Pull Request event
+
+The `RunAutoPlanCommand` function in the
+[command_runner.go](https://github.com/runatlantis/atlantis/blob/main/server/events/command_runner.go)
+file is called for the _Open_ and _Update_ Pull Request events. When enabled on
+the project, this automatically runs the `plan` for the specific repository.
+
+Whenever a Pull Request is closed, the `CleanUpPull` function in the
+[instrumented_pull_closed_executor.go](https://github.com/runatlantis/atlantis/blob/main/server/events/instrumented_pull_closed_executor.go)
+file is called. This function cleans up all the closed Pull Request files,
+locks, and other related information.

runatlantis.io/contributing/glossary.md

@@ -0,0 +1,26 @@
+# Glossary
+
+The Atlantis community uses many words and phrases to work more efficiently.
+You will find the most common ones and their meaning on this page.
+
+## Pull / Merge Request Event
+
+The different VCSs have different names for merging changes. Atlantis uses the
+name Pull Request as the abstraction. The VCS provider implements this
+abstraction and forwards the call to the respective function.
+
+## VCS
+
+VCS stands for Version Control System.
+
+Atlantis supports only git as a Version Control System. However, there is
+support for multiple VCS Providers. Currently, it supports the following
+providers:
+
+- [Azure DevOps](https://azure.microsoft.com/en-us/products/devops)
+- [BitBucket](https://bitbucket.org/)
+- [GitHub](https://github.com/)
+- [GitLab](https://gitlab.com/)
+- [Gitea](https://gitea.com/)
+
+The term VCS is used for both git and the different VCS providers.