|
| 1 | +# Nitric Repository Development Guidelines |
| 2 | + |
| 3 | +## Getting Started |
| 4 | + |
| 5 | +Get started with Nitric development by [forking the repository](https://github.com/nitrictech/nitric/fork) and cloning it to your local machine. |
| 6 | + |
| 7 | +```bash |
| 8 | +git clone https://github.com/<your-github-username>/nitric.git |
| 9 | +``` |
| 10 | + |
| 11 | +### Installation |
| 12 | + |
| 13 | +Requirements: |
| 14 | + |
| 15 | +- Git |
| 16 | +- Golang (1.22) |
| 17 | +- Make |
| 18 | +- Docker |
| 19 | +- Google Protocol Buffers Compiler (protoc) |
| 20 | + |
| 21 | +To install the `protoc-gen-go` tooling use: |
| 22 | + |
| 23 | +```bash |
| 24 | +make install-tools |
| 25 | +``` |
| 26 | + |
| 27 | +Once you have the tools installed you can install the go dependencies: |
| 28 | + |
| 29 | +```bash |
| 30 | +go mod tidy |
| 31 | +``` |
| 32 | + |
| 33 | +### Building Providers |
| 34 | + |
| 35 | +The following command will recursively go through all the providers in `cloud/` and build them into their respective `bin/` folders. |
| 36 | + |
| 37 | +```bash |
| 38 | +make binaries |
| 39 | +``` |
| 40 | + |
| 41 | +To install the provider binaries into `NITRIC_HOME` use: |
| 42 | + |
| 43 | +```bash |
| 44 | +make install |
| 45 | +``` |
| 46 | + |
| 47 | +In your stack file you can then use the version by specifying `0.0.1`, i.e. |
| 48 | + |
| 49 | +```yaml |
| 50 | +provider: nitric/aws@0.0.1 |
| 51 | +``` |
| 52 | +
|
| 53 | +### Testing |
| 54 | +
|
| 55 | +Run unit tests using: |
| 56 | +
|
| 57 | +```bash |
| 58 | +make test |
| 59 | +``` |
| 60 | + |
| 61 | +Run integration tests using: |
| 62 | + |
| 63 | +```bash |
| 64 | +make test-integration |
| 65 | +``` |
| 66 | + |
| 67 | +It can be useful to run a provider in a 'service only' mode to test the runtime or deployment components, where the cloud APIs are available but you don't need/want to start a child process to handle incoming request. This can be achieved by setting the MIN_WORKERS variable to `0`: |
| 68 | + |
| 69 | +```bash |
| 70 | +export MIN_WORKERS=0; ./cloud/aws/bin/deploy-aws |
| 71 | +``` |
| 72 | + |
| 73 | +## Custom Providers |
| 74 | + |
| 75 | +There are two main ways to create a custom provider: |
| 76 | + |
| 77 | +1. **Create a new provider:** This is the most flexible option, but also the most complex. You can [create a new provider from scratch](https://nitric.io/docs/providers/custom/create). |
| 78 | +2. **Extend an existing provider:** This is a good option if you want to leverage the existing provider's deployment automation and only need to make specific changes, such as use your own Terraform modules or deploy Nitric resources to a different cloud service. You [can extend an existing provider](https://nitric.io/docs/providers/custom/extend) to add your own configuration options or change the deployment process. |
| 79 | + |
| 80 | +## Documentation Contribution |
| 81 | + |
| 82 | +If you find a mistake or are interested in contributing to our documentation you can fork the [documentation repo](https://github.com/nitrictech/docs), clone to your local machine and then open a pull request. If you found a problem but don't have the time to make the changes directly, then a [opening up an issue](https://github.com/nitrictech/docs/issues/new/choose) is much appreciated. |
| 83 | + |
| 84 | +```bash |
| 85 | +git clone https://github.com/<your-github-username>/docs.git |
| 86 | +``` |
| 87 | + |
| 88 | +The docs repo is organised with all the documentation being under `/docs` and the images under `/public/images`. |
| 89 | + |
| 90 | +### Formatting |
| 91 | + |
| 92 | +All docs files are written using markdown, with some custom components written for the rendering ([shown below](#components)). |
| 93 | + |
| 94 | +When you open a pull request, tests will run in the GitHub actions that will spellcheck, check for broken links, and make sure all the formatting is correct. These scripts can be run locally using the following commands: |
| 95 | + |
| 96 | +```bash |
| 97 | +npm run test:spellchecker |
| 98 | + |
| 99 | +npm run format:fix |
| 100 | + |
| 101 | +npm run cypress |
| 102 | +``` |
| 103 | + |
| 104 | +If there is a word that is flagged by the spellchecker but is actually valid you can update the `dictionary.txt` file. |
| 105 | + |
| 106 | +### Components |
| 107 | + |
| 108 | +There are a few components that have been written specifically for the Nitric documentation. These require that the markdown is written in `.mdx` format. These components are listed below. |
| 109 | + |
| 110 | +If you would like to highlight something important you can use the `<Note>` component. This is normally reserved for common pitfalls, caveats, or warnings that a reader should take not of. |
| 111 | + |
| 112 | +``` |
| 113 | +<Note>Content that you want to be highlighted</Note> |
| 114 | +``` |
| 115 | + |
| 116 | +If you would like to have a title above your code examples, you can add metadata to the code markdown. This is generally reserved for adding file names to the tops of examples. |
| 117 | + |
| 118 | +```` |
| 119 | +```js title:example/document.js |
| 120 | +
|
| 121 | +``` |
| 122 | +```` |
| 123 | + |
| 124 | +For tabs to appear with the code examples with switchable languages, you can use the `<CodeSwitcher>` component. |
| 125 | + |
| 126 | +```` |
| 127 | +<CodeSwitcher> |
| 128 | +
|
| 129 | +```js title:example/document.js |
| 130 | +
|
| 131 | +``` |
| 132 | +
|
| 133 | +```python title:example/document.py |
| 134 | +
|
| 135 | +``` |
| 136 | +
|
| 137 | +</CodeSwitcher> |
| 138 | +```` |
| 139 | + |
| 140 | +### Frontmatter |
| 141 | + |
| 142 | +There is metadata that is required for every docs page. This metadata is stored in the frontmatter at the top of the page. For a default docs page it looks like so: |
| 143 | + |
| 144 | +``` |
| 145 | +--- |
| 146 | +description: 'Basic description for this page of example documentation' |
| 147 | +--- |
| 148 | +``` |
| 149 | + |
| 150 | +The guides require a bit more metadata as there is filtering that needs to happen on the [guides page](https://nitric.io/docs/guides). |
| 151 | + |
| 152 | +``` |
| 153 | +--- |
| 154 | +description: 'Description for this guide' |
| 155 | +tags: |
| 156 | + - A tag that can be used for filtering the guide |
| 157 | +languages: |
| 158 | + - javascript |
| 159 | + - typescript |
| 160 | + - python |
| 161 | + - dart |
| 162 | + - go |
| 163 | +image: /docs/images/guides/example-guide/banner.png |
| 164 | +image_alt: 'The featured image for the Example Guide' |
| 165 | +featured: |
| 166 | + image: /docs/images/guides/example-guide/featured.png |
| 167 | + image_alt: |
| 168 | +published_at: 2024-12-21 |
| 169 | +updated_at: 2024-12-21 |
| 170 | +--- |
| 171 | +``` |
| 172 | + |
| 173 | +## Community Channels |
| 174 | + |
| 175 | +- Ask questions in [GitHub discussions](https://github.com/nitrictech/nitric/discussions) |
| 176 | +- Join us on [Discord](https://nitric.io/chat) |
| 177 | +- Find us on [X](https://x.com/nitric_io) |
| 178 | +- Send us an [email](mailto:maintainers@nitric.io) |
0 commit comments