Skip to content

Latest commit

 

History

History
112 lines (68 loc) · 4.9 KB

CONTRIBUTING.md

File metadata and controls

112 lines (68 loc) · 4.9 KB
Raw

Contributing

Writing/Fixing Docs

Feel free to open an issue/a PR if you find something wrong in the docs.

Once you have submitted your PR, GitHub automatically builds the site and deploys a temporary preview to Netlify.

Style

A few style guidelines to help us keep a common style across documents:

  1. Use Reference-style Links. This makes reading the raw markdown and updating links easier.
  2. Prefer plain markdown over HTML/MDX. This makes reading the markdown easier.
  3. Use present tense rather than future tense. This makes the text easier to comprehend. Make an exception for planned or obsolete features, using future or past tense as appropriate.
  4. Use active voice rather than passive voice. This makes the text more engaging and easier to comprehend.

Local Development

Install the dependencies by running:

yarn

The below command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

yarn start

To develop in another language, use this command (setting your desired language):

yarn start --locale fr

This command generates static content and can be served using any static content hosting service.

yarn build

To build for only a specific language use:

yarn build --locale fr

Continuous Integration (CI)

We use a matrix of GitHub CI runners to build each locale in parallel. This enables us to keep build times down and also makes it easier to see the deploy logs live in GitHub.

On a PR being submitted, GitHub will then build the site then sent the results to Netlify to preview. The URL will be added to a comment in the PR upon a successful build.

On a push to the main branch, a build is triggered and then the resulting files will be sent to Netlify for publishing to prod.

Internationalization (i18n)

We're working with Crowdin to manage translations; if you feel like you want to lend a hand for translations, take a look at the documentation project: https://tauri.crowdin.com/documentation.

Translations are fetched and built built nightly at 12am UTC and then deployed as a preview on Netlify through a matrix of GitHub CI runners.

You can see the latest deploy preview here:

i18n-preview

To add a language to the site, add it to docusaurus.config.js's siteconfig.i18n.locales object.

The following items should be translated before enabling a language:

  • strings in i18n/[language] json files (generated by yarn docusaurus write-translations)
  • all files in docs/guides
  • all files in docs/about
  • all files in docs/.templates (these are used to generate docs/api/cli and docs/api/config)
  • all markdown files in src/pages

Crowdin Admin Note: You must setup a custom language mapping in the Crowdin UI since we're using a combination of Locale and 2-digit language codes. See the "Language Mapping" heading at the end of this section for instructions: https://support.crowdin.com/enterprise/project-settings/#export. You can also reference the currently configured mappings.

Versioning

Additional versioning references: Docusaurus

Only files in /docs/ will be "versioned".

There are 2 scenarios noted below. More information can be found on Docusaurus for both of these cases

Continue Working on Released Version's Docs

You are "releasing" a version but aren't planning to start working on a new version's docs yet. This could be if you've just released v1 and would like to continue working on the guides or updating API documentation for v1. You'd like this current version to be the default served to site visitors.

Nothing needs to be done! As long as you've set unreleasedTauriVersion in docusaurus.config.js, it will re-write the url to that value

Start Working on Unreleased Version's docs

You want to begin working on unreleased or beta docs. You would like to begin updating guides and APIs against the beta version. You would still like the non-beta version to be the default version served to site visitors.

For example, if you've launched v1 and would like to work on v2 docs but not serve them as the default, you would do the following:

  1. Update unreleasedTauriVersion in docusaurus.config.js to 'v2'
  2. Run the following command to version the current docs:
  3. Update .github/workflows/build.yml environment LATEST_VERSION to 'v2'
yarn docusaurus docs:version 'v1'

This value above should match what was previously in the unreleasedTauriVersion variable