How to Contribute

Thanks for thinking of contributing to Leaning Technologies open source projects and their documentation!

Quick links:

Your First Pull Request

Working on your first pull request? You can learn how here:

How to Contribute to an Open Source Project on GitHub

Bugs and Feature Requests

If you find a bug or have a feature request, please open an issue on the relevant repository or ask in the #support channel on our Discord server.

Documentation

Documentation is written in Markdown and MDX and is located in the src/content/docs directory of Labs.

Style guide

In brief:

Use Diataxis for structure
Be concise but thorough; you can always link to more information or provide it in a callout
Always use examples
Avoid “I” and “you”; use “we” if necessary

Labs

Labs is the codebase for the Leaning Technologies developer site. It is built using Astro, Tailwind, TypeScript, and Svelte.

Setup

Install Node.js
Install pnpm
Clone the repo, e.g. with gh clone leaningtech/labs
Change into the directory: cd labs/sites/labs
Install dependencies: pnpm install
Spawn development server: pnpm start
Visit localhost:4321

Linting

Linters run automatically in this GitHub Action workflow. You can also run them locally.

Prose

Vale checks style and grammar in Markdown files, like capitalisation of certain words, use of passive voice, and more.

Install Vale
Download style rules: vale sync
Check with Vale: vale .

For editor integration, use:

Visual Studio Code: chrischinchilla.vale-vscode
Vim: ALE

Vale is quite brittle, particularly on MDX files. It’s okay if there are errors, but please look at them to see if they are valid. Hopefully we can improve this in the future.

Prettier

Prettier is a code formatter. It’s shipped as a devDependency, so pnpm install will have installed it.

To format all files:

$ pnpm format

Astro diagnostics

Astro has some of its own diagnostics.

$ pnpm astro check

TypeScript

$ pnpm tsc