From 158d8dfc82c50eaedb97bdb64d3a9b9aca15a067 Mon Sep 17 00:00:00 2001 From: Michael Schurter Date: Thu, 6 Jun 2019 12:18:45 -0700 Subject: [PATCH] docs: initial attempt at developer docs --- README.md | 5 ++++- docs/README.md | 38 ++++++++++++++++++++++++++++++++++++++ docs/checklist-command.md | 32 ++++++++++++++++++++++++++++++++ docs/checklist-jobspec.md | 25 +++++++++++++++++++++++++ 4 files changed, 99 insertions(+), 1 deletion(-) create mode 100644 docs/README.md create mode 100644 docs/checklist-command.md create mode 100644 docs/checklist-jobspec.md diff --git a/README.md b/README.md index 2ad0f8e23..f2207b532 100644 --- a/README.md +++ b/README.md @@ -140,7 +140,10 @@ Who Uses Nomad Contributing to Nomad -------------------- -If you wish to contribute to Nomad, you will need [Go](https://www.golang.org) installed on your machine (version 1.10.2+ is *required*). +If you wish to contribute to Nomad, you will need [Go](https://www.golang.org) +installed on your machine (version 1.10.2+ is *required*). + +See the [`docs`](docs/) directory for more developer documentation. **Developing with Vagrant** There is an included Vagrantfile that can help bootstrap the process. The diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..cb462a23a --- /dev/null +++ b/docs/README.md @@ -0,0 +1,38 @@ +# 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. + +The high level control flow for many Nomad commands are: + +``` +# Read commands: +CLI command -> HTTP API -> RPC -> StateStore + +# Commands that change state: +CLI command -> 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) diff --git a/docs/checklist-command.md b/docs/checklist-command.md new file mode 100644 index 000000000..9cf7de829 --- /dev/null +++ b/docs/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 + +1. [ ] New file in `command/` or in an existing file if a subcommand +2. [ ] Test new command in `command/` package +3. [ ] Implement autocomplete +4. [ ] Implement `-json` (returns raw API response) +5. [ ] Implement `-verbose` (expands truncated UUIDs, adds other detail) +7. [ ] Update help text +7. [ ] Implement and test new HTTP endpoint in `command/agent/_endpoint.go` +8. [ ] Implement and test new RPC endpoint in `nomad/_endpoint.go` +9. [ ] Implement and test new Client RPC endpoint in `client/_endpoint.go` + * For client endpoints only (e.g. Filesystem) +10. [ ] Implement and test new `api/` package Request and Response structs +11. [ ] Implement and test new `api/` package helper methods +12. [ ] Implement and test new `nomad/structs/` package Request and Response structs + +## Docs + +1. [ ] Changelog +2. [ ] API docs https://www.nomadproject.io/api/index.html +3. [ ] CLI docs https://www.nomadproject.io/docs/commands/index.html +4. [ ] Consider if it needs a guide https://www.nomadproject.io/guides/index.html diff --git a/docs/checklist-jobspec.md b/docs/checklist-jobspec.md new file mode 100644 index 000000000..aad500bf0 --- /dev/null +++ b/docs/checklist-jobspec.md @@ -0,0 +1,25 @@ +# New `jobspec` Entry Checklist + +## Code + +1. [ ] Parse in `jobspec/parse.go` +2. [ ] Test in `jobspec/parse_test.go` (preferably with a + `jobspec/text-fixtures/.hcl` test file) +3. [ ] 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 +4. [ ] Add structs/fields to `nomad/structs` package + * Validation happens in this package and must be implemented + * Implement other methods and tests from `api/` package +5. [ ] Add conversion between `api/` and `nomad/structs` in `command/agent/job_endpoint.go` +6. [ ] Test conversion + +## Docs + +1. [ ] Changelog +2. [ ] Jobspec entry https://www.nomadproject.io/docs/job-specification/index.html +3. [ ] Job JSON API entry https://www.nomadproject.io/api/json-jobs.html +4. [ ] Sample Response output in API https://www.nomadproject.io/api/jobs.html +5. [ ] Consider if it needs a guide https://www.nomadproject.io/guides/index.html