github.com/Ilhicas/nomad@v1.0.4-0.20210304152020-e86851182bc3/contributing/README.md (about)

     1  Nomad Codebase Documentation
     2  ===
     3  
     4  This directory contains some documentation about the Nomad codebase,
     5  aimed at readers who are interested in making code contributions.
     6  
     7  If you're looking for information on _using_ Nomad, please instead refer
     8  to the [Nomad website](https://nomadproject.io).
     9  
    10  Developing with Vagrant
    11  ---
    12  A development environment is supplied via Vagrant to make getting started easier.
    13  
    14  1. Install [Vagrant](https://www.vagrantup.com/docs/installation)
    15  1. Install [Virtualbox](https://www.virtualbox.org/)
    16  1. Bring up the Vagrant project
    17      ```sh
    18      $ git clone https://github.com/hashicorp/nomad.git
    19      $ cd nomad
    20      $ vagrant up
    21      ```
    22  
    23      The virtual machine will launch, and a provisioning script will install the
    24      needed dependencies within the VM.
    25  
    26  1. SSH into the VM
    27      ```sh
    28      $ vagrant ssh
    29      ```
    30  
    31  Developing without Vagrant
    32  ---
    33  1. Install [Go 1.15.6+](https://golang.org/) *(Note: `gcc-go` is not supported)*
    34  1. Clone this repo
    35     ```sh
    36     $ git clone https://github.com/hashicorp/nomad.git
    37     $ cd nomad
    38     ```
    39  1. Bootstrap your environment
    40     ```sh
    41     $ make bootstrap
    42     ```
    43  1. (Optionally) Set a higher ulimit, as Nomad creates many file handles during normal operations
    44     ```sh
    45     $ [ "$(ulimit -n)" -lt 1024 ] && ulimit -n 1024
    46     ```
    47  1. Verify you can run tests
    48     ```sh
    49     $ make test
    50     ```
    51  
    52  Running a development build
    53  ---
    54  1. Compile a development binary (see the [UI README](https://github.com/hashicorp/nomad/blob/master/ui/README.md) to include the web UI in the binary)
    55      ```sh
    56      $ make dev
    57      # find the built binary at ./bin/nomad
    58      ```
    59  1. Start the agent in dev mode
    60      ```sh
    61      $ sudo bin/nomad agent -dev
    62      ```
    63  1. (Optionally) Run Consul to enable service discovery and health checks
    64      1. Download [Consul](https://www.consul.io/downloads)
    65      1. Start Consul in dev mode
    66          ```sh
    67          $ consul agent -dev
    68          ```
    69  
    70  Compiling Protobufs
    71  ---
    72  If in the course of your development you change a Protobuf file (those ending in .proto), you'll need to recompile the protos.
    73  
    74  1. Install [Buf](https://docs.buf.build/installation)
    75  1. Compile Protobufs
    76      ```sh
    77      $ make proto
    78      ```
    79  
    80  Building the Web UI
    81  ---
    82  See the [UI README](https://github.com/hashicorp/nomad/blob/master/ui/README.md) for instructions.
    83  
    84  Create a release binary
    85  ---
    86  To create a release binary:
    87  
    88  ```sh
    89  $ make prerelease
    90  $ make release
    91  $ ls ./pkg
    92  ```
    93  
    94  This will generate all the static assets, compile Nomad for multiple
    95  platforms and place the resulting binaries into the `./pkg` directory.
    96  
    97  API Compatibility
    98  --------------------
    99  Only the `api/` and `plugins/` packages are intended to be imported by other projects. The root Nomad module does not follow semver and is not intended to be imported directly by other projects.
   100  
   101  ## Architecture
   102  
   103  The code for Nomad's major components is organized as:
   104  
   105  * `api/` provides a Go client for Nomad's HTTP API.
   106  * `client/` contains Nomad's client agent code.
   107  * `command/` contains Nomad's CLI code.
   108  * `nomad/` contains Nomad's server agent code.
   109  * `ui/` contains Nomad's UI code.
   110  * `website/` contains Nomad's website and documentation.
   111  
   112  The high level control flow for many Nomad actions (via the CLI or UI) are:
   113  
   114  ```
   115  # Read actions:
   116  Client -> HTTP API -> RPC -> StateStore
   117  
   118  # Actions that change state:
   119  Client -> HTTP API -> RPC -> Raft -> FSM -> StateStore
   120  ```
   121  
   122  Checklists
   123  ---
   124  
   125  When adding new features to Nomad there are often many places to make changes.
   126  It is difficult to determine where changes must be made and easy to make
   127  mistakes.
   128  
   129  The following checklists are meant to be copied and pasted into PRs to give
   130  developers and reviewers confidence that the proper changes have been made:
   131  
   132  * [New `jobspec` entry](checklist-jobspec.md)
   133  * [New CLI command](checklist-command.md)
   134  * [New RPC endpoint](checklist-rpc-endpoint.md)
   135  
   136  Tooling
   137  ---
   138  
   139  * [Go tool versions](golang.md)