Dev guide

CONTRIBUTING.md

@@ -1,24 +1,24 @@
 ## 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.
 
 Our team encourages you to ask questions, raise requests for new features and let us know about bugs!
 
 ### 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
 

DEVELOPERS.md

@@ -0,0 +1,178 @@
+# Nitric Repository Development Guidelines
+
+## Getting Started
+
+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/<your-github-username>/nitric.git
+```
+
+### Installation
+
+Requirements:
+
+- Git
+- Golang (1.22)
+- Make
+- Docker
+- Google Protocol Buffers Compiler (protoc)
+
+To install the `protoc-gen-go` tooling use:
+
+```bash
+make install-tools
+```
+
+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 provider binaries into `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/[email protected]
+```
+
+### 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.
+
+## 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.
+
+```bash
+git clone https://github.com/<your-github-username>/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
+
+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 `<Note>` component. This is normally reserved for common pitfalls, caveats, or warnings that a reader should take not of.
+
+```
+<Note>Content that you want to be highlighted</Note>
+```
+
+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 `<CodeSwitcher>` component.
+
+````
+<CodeSwitcher>
+
+```js title:example/document.js
+
+```
+
+```python title:example/document.py
+
+```
+
+</CodeSwitcher>
+````
+
+### 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
+---
+```
+
+## Community Channels
+
+- Ask questions in [GitHub discussions](https://github.com/nitrictech/nitric/discussions)
+- Join us on [Discord](https://nitric.io/chat)
+- Find us on [X](https://x.com/nitric_io)
+- Send us an [email](mailto:[email protected])

README.md

@@ -43,7 +43,7 @@ We also know abstraction should mean building on existing layers, not hiding the
   <a href="./cloud/azure"><img src="https://skillicons.dev/icons?i=azure"/></a>
 </p>
 
-> 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).