From a1d1d6be312e55740a662970018d7145d5069f98 Mon Sep 17 00:00:00 2001 From: Ryan Cartwright Date: Wed, 18 Dec 2024 20:12:24 +1100 Subject: [PATCH 1/5] wip dev guide --- CONTRIBUTING.md | 2 +- DEVELOPERS.md | 109 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 6 +-- 3 files changed, 113 insertions(+), 4 deletions(-) create mode 100644 DEVELOPERS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4036762b4..c0733157f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ ## Contributions -Thanks for your interest in contributing to the Nitric community. +Thanks for your interest in contributing to the Nitric community. If you want specifics about contributing to the documentation or the Nitric repo, take a look at the [development guide](./DEVELOPERS.md). There are plenty of ways to get involved, we've summarized a few here to get you started. diff --git a/DEVELOPERS.md b/DEVELOPERS.md new file mode 100644 index 000000000..b80ef4125 --- /dev/null +++ b/DEVELOPERS.md @@ -0,0 +1,109 @@ +# Nitric Repository Development Guidelines + +## Getting Started + +Get started with Nitric development by forking the repository and cloning it to your local machine. + +```bash +git clone https://github.com//nitric.git +``` + +### Installation + +```bash +go mod tidy +``` + +Requirements: + +- Git +- Golang (1.22) +- Make +- Docker +- Google Protocol Buffers Compiler (protoc) + +To install dependencies use: + +```bash +make install-tools +``` + +### Building + +```bash +make binaries +``` + +To install the binaries into your nitric home use: + +```bash +make install +``` + +In your stack file you can then use the version by specifying `0.0.1`, i.e. + +```yaml +provider: nitric/aws@0.0.1 +``` + +### Testing + +Run unit tests using: + +```bash +make test +``` + +Run integration tests using: + +```bash +make test-integration +``` + +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`: + +```bash +export MIN_WORKERS=0; ./cloud/aws/bin/deploy-aws +``` + +## Custom Providers + +There are two main ways to create a custom provider: + +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). +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. + +## Community Channels + +- Ask questions in [GitHub discussions](https://github.com/nitrictech/nitric/discussions) +- Join us on [Discord](https://nitric.io/chat) +- Find us on [Twitter](https://twitter.com/nitric_io) +- Send us an [email](mailto:maintainers@nitric.io) + +# Documentation + +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. + +```bash +git clone https://github.com//docs.git +``` + +The docs repo is organised with all the documentation being under `/docs` and the images under `/public/images`. + +### Formatting + +All docs files are written using markdown, with some custom components written for the rendering ([shown below](#components)). + +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: + +```bash +npm run test:spellchecker + +npm run format:fix + +npm run cypress +``` + +If there is a word that is flagged by the spellchecker but is actually valid you can update the `dictionary.txt` file. + +### Components diff --git a/README.md b/README.md index 04954adb2..e291e0bc9 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ We also know abstraction should mean building on existing layers, not hiding the

-> These are supported out of the box, but you can also build [custom providers](https://nitric.io/docs/reference/providers/custom/building-custom-provider) as well +> These are supported out of the box, but you can also build [custom providers](https://nitric.io/docs/providers/custom/create) as well ## 🧑‍💻 Get started @@ -118,7 +118,7 @@ main.post("/notes/:title", async (ctx) => { }); ``` -This is the only code needed to deploy a working application to any cloud provider using [`nitric up`](https://nitric.io/docs/getting-started/deployment). Nitric can deploy this application using automatically generated [Pulumi](https://nitric.io/docs/reference/providers/pulumi), [Terraform](https://nitric.io/docs/reference/providers/terraform) or [any other automation tools](https://nitric.io/docs/reference/providers/custom/building-custom-provider) of your choice. +This is the only code needed to deploy a working application to any cloud provider using [`nitric up`](https://nitric.io/docs/get-started/foundations/deployment). Nitric can deploy this application using automatically generated [Pulumi](https://nitric.io/docs/providers/pulumi), [Terraform](https://nitric.io/docs/providers/terraform) or [any other automation tools](https://nitric.io/docs/providers/custom/create) of your choice. ## Why use Nitric? @@ -148,4 +148,4 @@ Nitric has full documentation at [nitric.io/docs](https://nitric.io/docs), inclu ## Contributing -We greatly appreciate contributions, consider starting with the [contributions guide](./CONTRIBUTING.md) and a chat on [Discord](https://nitric.io/chat) or [GitHub](https://github.com/nitrictech/nitric/discussions). +We greatly appreciate contributions, consider starting with the [contributions guide](./CONTRIBUTING.md) or [development guide](./DEVELOPERS.md), and a chat on [Discord](https://nitric.io/chat) or [GitHub](https://github.com/nitrictech/nitric/discussions). From e6edfc58d72dfe236388424148ec0476ab285f37 Mon Sep 17 00:00:00 2001 From: Ryan Cartwright Date: Thu, 19 Dec 2024 18:25:45 +1100 Subject: [PATCH 2/5] add documentation contribution --- DEVELOPERS.md | 67 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 66 insertions(+), 1 deletion(-) diff --git a/DEVELOPERS.md b/DEVELOPERS.md index b80ef4125..a572454bf 100644 --- a/DEVELOPERS.md +++ b/DEVELOPERS.md @@ -80,7 +80,7 @@ There are two main ways to create a custom provider: - Find us on [Twitter](https://twitter.com/nitric_io) - Send us an [email](mailto:maintainers@nitric.io) -# Documentation +# Documentation Contribution 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. @@ -107,3 +107,68 @@ npm run cypress If there is a word that is flagged by the spellchecker but is actually valid you can update the `dictionary.txt` file. ### Components + +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. + +If you would like to highlight something important you can use the `` component. This is normally reserved for common pitfalls, caveats, or warnings that a reader should take not of. + +``` +Content that you want to be highlighted +``` + +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. + +```` +```js title:example/document.js + +``` +```` + +For tabs to appear with the code examples with switchable languages, you can use the `` component. + +```` + + +```js title:example/document.js + +``` + +```python title:example/document.py + +``` + + +```` + +### Frontmatter + +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: + +``` +--- +description: 'Basic description for this page of example documentation' +--- +``` + +The guides require a bit more metadata as there is filtering that needs to happen on the [guides page](https://nitric.io/docs/guides). + +``` +--- +description: 'Description for this guide' +tags: + - A tag that can be used for filtering the guide +languages: + - javascript + - typescript + - python + - dart + - go +image: /docs/images/guides/example-guide/banner.png +image_alt: 'The featured image for the Example Guide' +featured: + image: /docs/images/guides/example-guide/featured.png + image_alt: +published_at: 2024-12-21 +updated_at: 2024-12-21 +--- +``` From 7f0c8aa97b3558c2fb364eeeb3a1e67a01ec5020 Mon Sep 17 00:00:00 2001 From: Ryan Cartwright Date: Tue, 31 Dec 2024 15:54:07 +1100 Subject: [PATCH 3/5] add additional context --- DEVELOPERS.md | 34 +++++++++++++++++++--------------- 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/DEVELOPERS.md b/DEVELOPERS.md index a572454bf..b871521c8 100644 --- a/DEVELOPERS.md +++ b/DEVELOPERS.md @@ -10,10 +10,6 @@ git clone https://github.com//nitric.git ### Installation -```bash -go mod tidy -``` - Requirements: - Git @@ -22,19 +18,27 @@ Requirements: - Docker - Google Protocol Buffers Compiler (protoc) -To install dependencies use: +To install the `protoc-gen-go` tooling use: ```bash make install-tools ``` -### Building +Once you have the tools installed you can install the go dependencies: + +```bash +go mod tidy +``` + +### Building Providers + +The following command will recursively go through all the providers in `cloud/` and build them into their respective `bin/` folders. ```bash make binaries ``` -To install the binaries into your nitric home use: +To install the provider binaries into `NITRIC_HOME` use: ```bash make install @@ -73,14 +77,7 @@ There are two main ways to create a custom provider: 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). 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. -## Community Channels - -- Ask questions in [GitHub discussions](https://github.com/nitrictech/nitric/discussions) -- Join us on [Discord](https://nitric.io/chat) -- Find us on [Twitter](https://twitter.com/nitric_io) -- Send us an [email](mailto:maintainers@nitric.io) - -# Documentation Contribution +## Documentation Contribution 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. @@ -172,3 +169,10 @@ published_at: 2024-12-21 updated_at: 2024-12-21 --- ``` + +## Community Channels + +- Ask questions in [GitHub discussions](https://github.com/nitrictech/nitric/discussions) +- Join us on [Discord](https://nitric.io/chat) +- Find us on [Twitter](https://twitter.com/nitric_io) +- Send us an [email](mailto:maintainers@nitric.io) From 42cdcba392f66c15880f6d49f182c946576279e4 Mon Sep 17 00:00:00 2001 From: David Moore Date: Tue, 7 Jan 2025 14:55:47 +1100 Subject: [PATCH 4/5] fix links in contributing.md --- CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c0733157f..903b8edfa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,17 +8,17 @@ Our team encourages you to ask questions, raise requests for new features and le ### Ask a question about Nitric -You can ask questions and launch discussions about Nitric-related topics in the nitric repository on [GitHub](https://github.com/nitrictech/nitric/core/discussions). +You can ask questions and launch discussions about Nitric-related topics in the nitric repository on [GitHub](https://github.com/nitrictech/nitric/discussions). ### Submit a feature request -You can ask questions and launch discussions about Nitric-related topics in the nitric repository on [GitHub](https://github.com/nitrictech/nitric/core/issues/new?assignees=&labels=&template=feature_request.md&title=%27Submit%20feature%20request%27). +You can ask questions and launch discussions about Nitric-related topics in the nitric repository on [GitHub](https://github.com/nitrictech/nitric/issues/new?assignees=&labels=enhancement&projects=&template=2.feature.md). ### Create a bug report for Nitric -If you find any error messages or run into issues whilst using the Nitric Platform, please make sure to create a [bug report](https://github.com/nitrictech/nitric/core/issues/new?assignees=&labels=&template=bug_report.md&title=%27Create%20bug%20report%27). +If you find any error messages or run into issues whilst using the Nitric Platform, please make sure to create a [bug report](https://github.com/nitrictech/nitric/issues/new?assignees=&labels=bug&projects=&template=1.bug.md). -You can also check out our [Creating bug reports](https://nitric.io/docs/support/bug-report) guide to step you through the process. +You can also check out our [Creating bug reports](https://nitric.io/docs/misc/support#best-practices-for-writing-the-bug-report) guide to step you through the process. ### Issues and smaller features From 125905975acdce0bcb7a6df61188e2f0eeafdf65 Mon Sep 17 00:00:00 2001 From: David Moore Date: Tue, 7 Jan 2025 15:06:58 +1100 Subject: [PATCH 5/5] a few improvements for developers.md --- DEVELOPERS.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/DEVELOPERS.md b/DEVELOPERS.md index b871521c8..3cf4a6a85 100644 --- a/DEVELOPERS.md +++ b/DEVELOPERS.md @@ -2,7 +2,7 @@ ## Getting Started -Get started with Nitric development by forking the repository and cloning it to your local machine. +Get started with Nitric development by [forking the repository](https://github.com/nitrictech/nitric/fork) and cloning it to your local machine. ```bash git clone https://github.com//nitric.git @@ -74,8 +74,8 @@ export MIN_WORKERS=0; ./cloud/aws/bin/deploy-aws There are two main ways to create a custom provider: -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). -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. +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). +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. ## Documentation Contribution @@ -174,5 +174,5 @@ updated_at: 2024-12-21 - Ask questions in [GitHub discussions](https://github.com/nitrictech/nitric/discussions) - Join us on [Discord](https://nitric.io/chat) -- Find us on [Twitter](https://twitter.com/nitric_io) +- Find us on [X](https://x.com/nitric_io) - Send us an [email](mailto:maintainers@nitric.io)