Skip to content

Latest commit

 

History

History
151 lines (113 loc) · 6.98 KB

CONTRIBUTING.md

File metadata and controls

151 lines (113 loc) · 6.98 KB

Contributing

Thanks for being here and for being awesome! 👍

The following sections outline the different ways to contribute to the project.

Repository Organization

SaladCloud documentation follows Diátaxis principles.

Diataxis framework

In our documentation, we label the "Explanation" section "Products", but otherwise, the structure is the same.

  • Products: Information about the products, what they do, what they cost, and how to use them.
  • Tutorials: Step-by-step guides which teach how to use the products. These do not try to achieve a particular outcome, but rather to teach a particular skill. They do not assume background knowledge.
  • How-to Guides: Guides that explain how to do something of practical value, using the products. They assume some background knowledge.
  • Reference: API documentation for the products.

Directory Structure And Standards

  • The directory structure should match the final website structure, i.e. the path /products/documentation should be represented by a file products/documentation.mdx.
  • Images should be placed in a sibling directory to the markdown file that references them, named images.
products/sce/gateway
├── images
│   ├── container-gateway-error-400.png
│   ├── container-gateway-error-401.png
│   ├── container-gateway-error-403.png
│   ├── container-gateway-error-404.png
│   ├── container-gateway-error-408.png
│   ├── container-gateway-error-410.png
│   ├── container-gateway-error-413.png
│   ├── container-gateway-error-500.png
│   ├── container-gateway-error-501.png
│   ├── container-gateway-error-502.png
│   ├── container-gateway-error-503.png
│   ├── container-gateway-error-504.png
│   ├── load-balancer-options-1.png
│   ├── portal-access-domain-name.png
│   ├── portal-enable-authentication.png
│   └── portal-enable-container-gateway.png
├── enabling-ipv6.mdx
├── error-pages.mdx
├── load-balancer-options.mdx
├── sending-requests.mdx
└── websockets.mdx
  • Files should be named with kebab-case, using full words. For example, load-balancer-options.mdx is preferred over lb-opts.mdx. This applies to image files as well.
  • All content should pass the spell checker. We use cspell to check spelling. You can run npx cspell "**/*.{md,mdx}" to check spelling on all markdown files. There is a GitHub action that will check spelling on all PRs. If you see a spelling error, please fix it.
  • All content should pass the Prettier code formatter. You can run npx prettier --write . to format all files. There is a GitHub action that will check formatting on all PRs. If you see a formatting error, please fix it.

Discussing

The easiest way to contribute to the project is by participating in community discussions on the SaladCloud Discord server. The community often chimes in with helpful advice when you have a question, and you may also find yourself providing answers and helping others. Be sure to review the code of conduct before participating.

Please do not use GitHub issues to ask a question. We will politely close a GitHub issue that asks a question and kindly refer you to the SaladCloud Discord server or official support.

Please do not use public GitHub issues to report a security vulnerability. Instead, refer to our security policy for responsible disclosure options.

Reporting Issues

You can create a GitHub issue to report problems with our documentation. You can also contact official support if you found a problem with the product.

Please do not use public GitHub issues to report a security vulnerability. Instead, refer to our security policy for responsible disclosure options.

Reporting Security Vulnerabilities

We take security seriously, and we appreciate your cooperation in disclosing vulnerabilities to us responsibly. Refer to our security policy for more details.

Please do not use public GitHub issues to report a security vulnerability.

Changing Code

Interested in changing the world?

First, setup your local development environment. You need Visual Studio Code and a recent version of Node.js installed (we recommend the latest LTS version).

Second, fork this repository and clone your fork to your local machine.

Third, open the project in Visual Studio Code and install the recommended workspace extensions. Refer to the Visual Studio Code documentation on recommended extensions to learn more.

Fourth, create a new branch for your changes, make your modifications, and commit them with a clear message.

Finally, push your changes to your fork and create a pull request against this repository.

Additionally, please consider taking a moment to read Miguel de Icaza's blog post titled Open Source Contribution Etiquette and Ilya Grigorik's blog post titled Don't "Push" Your Pull Requests.

Adding Endpoints

To add a new endpoint (like dreambooth or transcription) to the documentation, follow these steps:

  1. Place the openapi3 compatible input and output json schema for the endpoint in the scripts/inputs-and-outputs directory

  2. Place a config file in scripts/endpoint-schema-configs, with the following structure:

    {
  "baseSchema": "api-specs/salad-cloud.json",
  "inputSchema": "scripts/inputs-and-outputs/dreambooth-sd15-input.json",
  "outputSchema": "scripts/inputs-and-outputs/dreambooth-output.json",
  "endpointId": "dreambooth-sd15",
  "endpointName": "Dreambooth Training API - Stable Diffusion 1.5",
  "schemaName": "DreamboothSD15Training",
  "apiDocPath": "reference/dreambooth/sd15"
}

  3. To run all config files, use ./scripts/add-all-endpoints

Adding Recipes

To add a new recipe to the documentation, follow these steps:

  1. Place the openapi3 spec for the recipe in the api-specs directory, named for the recipe. It should match the directory name in the salad-recipes repository.
  2. Run ./scripts/add-recipe <path-to-spec> to generate the recipe pages.
  3. Add the recipe to the navigation in mint.json. Find the navigation array in mint.json, and add your recipe pages to the appropriate section.