Merge pull request #5786 from hashicorp/docs-docs

docs: initial attempt at developer docs

README.md

@@ -142,6 +142,8 @@ Contributing to Nomad
 
 If you wish to contribute to Nomad, you will  need [Go](https://www.golang.org) installed on your machine (version 1.11.11+ is *required*).
 
+See the [`contributing`](contributing/) directory for more developer documentation.
+
 **Developing with Vagrant**
 There is an included Vagrantfile that can help bootstrap the process. The
 created virtual machine is based off of Ubuntu 16, and installs several of the

contributing/README.md

@@ -0,0 +1,40 @@
+# Nomad Codebase Documentation
+
+This directory contains some documentation about the Nomad codebase,
+aimed at readers who are interested in making code contributions.
+
+If you're looking for information on _using_ using, please instead refer
+to [the main Nomad website](https://nomadproject.io).
+
+## Architecture
+
+The code for Nomad's major components is organized as:
+
+* `api/` provides a Go client for Nomad's HTTP API.
+* `client/` contains Nomad's client agent code.
+* `command/` contains Nomad's CLI code.
+* `nomad/` contains Nomad's server agent code.
+* `ui/` contains Nomad's UI code.
+* `website/` contains Nomad's website and documentation.
+
+The high level control flow for many Nomad actions (via the CLI or UI) are:
+
+```
+# Read actions:
+Client -> HTTP API -> RPC -> StateStore
+
+# Actions that change state:
+Client -> HTTP API -> RPC -> Raft -> FSM -> StateStore
+```
+
+## Checklists
+
+When adding new features to Nomad there are often many places to make changes.
+It is difficult to determine where changes must be made and easy to make
+mistakes.
+
+The following checklists are meant to be copied and pasted into PRs to give
+developers and reviewers confidence that the proper changes have been made:
+
+* [New `jobspec` entry](checklist-jobspec.md)
+* [New CLI command](checklist-command.md)

contributing/checklist-command.md

@@ -0,0 +1,32 @@
+# New CLI command
+
+Subcommands should always be preferred over adding more top-level commands.
+
+Code flow for commands is generally:
+
+```
+CLI (command/) -> API Client (api/) -> HTTP API (command/agent) -> RPC (nomad/)
+```
+
+## Code
+
+*  [ ] New file in `command/` or in an existing file if a subcommand
+*  [ ] Test new command in `command/` package
+*  [ ] Implement autocomplete
+*  [ ] Implement `-json` (returns raw API response)
+*  [ ] Implement `-verbose` (expands truncated UUIDs, adds other detail)
+*  [ ] Update help text
+*  [ ] Implement and test new HTTP endpoint in `command/agent/<command>_endpoint.go`
+*  [ ] Implement and test new RPC endpoint in `nomad/<command>_endpoint.go`
+*  [ ] Implement and test new Client RPC endpoint in
+    `client/<command>_endpoint.go` (For client endpoints like Filesystem only)
+* [ ] Implement and test new `api/` package Request and Response structs
+* [ ] Implement and test new `api/` package helper methods
+* [ ] Implement and test new `nomad/structs/` package Request and Response structs
+
+## Docs
+
+* [ ] Changelog
+* [ ] API docs https://www.nomadproject.io/api/index.html
+* [ ] CLI docs https://www.nomadproject.io/docs/commands/index.html
+* [ ] Consider if it needs a guide https://www.nomadproject.io/guides/index.html

contributing/checklist-jobspec.md

@@ -0,0 +1,25 @@
+# New `jobspec` Entry Checklist
+
+## Code
+
+* [ ] Parse in `jobspec/parse.go`
+* [ ] Test in `jobspec/parse_test.go` (preferably with a
+  `jobspec/text-fixtures/<feature>.hcl` test file)
+* [ ] Add structs/fields to `api/` package
+  * structs usually have Canonicalize, Copy, and Merge methods
+  * New fields should be added to existing Canonicalize, Copy, and Merge
+    methods
+  * Test the struct/field via all methods mentioned above
+* [ ] Add structs/fields to `nomad/structs` package
+  * Validation happens in this package and must be implemented
+  * Implement other methods and tests from `api/` package
+* [ ] Add conversion between `api/` and `nomad/structs` in `command/agent/job_endpoint.go`
+* [ ] Test conversion
+
+## Docs
+
+* [ ] Changelog
+* [ ] Jobspec entry https://www.nomadproject.io/docs/job-specification/index.html
+* [ ] Job JSON API entry https://www.nomadproject.io/api/json-jobs.html
+* [ ] Sample Response output in API https://www.nomadproject.io/api/jobs.html
+* [ ] Consider if it needs a guide https://www.nomadproject.io/guides/index.html