kemko/nomad
1
0
Fork 0
mirror of https://github.com/kemko/nomad.git synced 2026-01-01 16:05:42 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs: initial attempt at developer docs

Browse Source
This commit is contained in:
Michael Schurter
2019-06-06 12:18:45 -07:00
parent 4293c6d6b5
commit 158d8dfc82
4 changed files with 99 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
README.md
View File

@@ -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

38
docs/README.md Normal file
View File

@@ -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)

32
docs/checklist-command.md Normal file
View File

@@ -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/<command>_endpoint.go`
8. [ ] Implement and test new RPC endpoint in `nomad/<command>_endpoint.go`
9. [ ] Implement and test new Client RPC endpoint in `client/<command>_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

25
docs/checklist-jobspec.md Normal file
View File

@@ -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/<feature>.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