Contribute, and help us improve

Tip

Call for translators! We’re looking for translators to help translate this spec for everyone!

Help improve the all-contributors documentation!

Thanks for your interest in the project! Pull Requests are welcome for any type of improvement, from a small typo to a new section in the docs. Help us make the project better!

All of the source code for the documentation is available in this repository here: github.com/all-contributors/all-contributors

The all-contributors bot lives in the app repository here:

And the all-contributors CLI lives in the cli repository here:

Committing to an all-contributors repo

We use the angular commit convention for commits that are used for an automated changelog generation, so it would be advisable to respect that. If you’re not used to it or are afraid to mistype a commit, you can run npm run commit or git cz (if you have installed commitizen) which would take you through a few questions and write the commit for you.

Editing Content

Tip

Every page has an Edit button up the top, clicking this will take you straight to the GitHub source code for that page

Once on a file, click the ‘pencil’ icon to easily edit the file inline After making your changes, scroll to the bottom of the page to create a commit with your changes. You will want to create and commit these changes on a new branch in your fork of the repository.

After committing your changes, you can create a pull request to propose your changes to be merged into the main branch.

Translations

Our translations are managed through crowdin. You can help contribute by heading to the crowdin project and suggesting translations. If you like, comment on this issue to let us know you’re helping or if you have any queries!

When translating, anything that has the XPATH @href, @src etc mustn’t be translated. Things like code should not be either. This will cause the project to 404. See the below image for an example:

However, it’s recommended to translate any content that would contribute to a better comprehension like the comments in code tags as long as it doesn’t change the actual code since it only understands English.

How to’s

Login to Crowdin

1. Go to the crowdin project, then sign up and/or log in.
2. Join the “All Contributors” project and voila!

Translate strings

1. Go to the crowdin project.
2. Click on the flag of the language you want to translate the documentation to.
3. Click on any *.md files that aren’t completely translated (read showing 100% on the right-hand side)
4. Write your translation in the “Enter translation here” field (which would correspond to the translation of the text in the “SOURCE STRING” field above) then click “SAVE”
5. For proofreaders only: You can either approve translation suggestions (whether it’s done by you or someone else), which you will find in the “[LANGUAGE] TRANSLATIONS” section, by clicking on the :ballot_box_with_check: or delete them by clicking on the :wastebasket: icon.

Change deployments

After you translate strings in any given language, you won’t see those changes appearing live until the main branch was updated followed by a successful deployment.

Run the website locally:

All Contributors currently uses Astro and the Starlight theme for our documentation and website.

To build the docs locally:

Make sure npm is installed on your machine. Use the nodejs documentation if you aren’t sure how to install npm.

To check that npm is installed run the following in your favorite shell:

npm -v

Next, make sure you have at least node version 0.22 (LTS) or higher. To check the version, use:

node -v

If you don’t have atleast version .22 or higher, please install node or upgrade your current version.

Install Astro, the Starlight Theme and all of the project dependencies using npm i.

npm i is shorthand for npm install

Once you have completed the above, you can launch a server locally that will build and run the docs locally. In your favorite shell run:

npm run start

• Then, go to http://localhost:4321 and you will see the all contributors website there!
• Refresh the browser page as needed when editing markdown pages.

Linting your contribution

If you make changes to a markdown file in the site, then our linting action will check those changes. To run the linter yourself locally on the documentation before submitting a PR use:

npm run lint

You can also run it manually on specific files like this:

markdownlint --fix "src/content/docs/contribute.md"

Checking links

We use Lychee, a fast rust-based link checker, to check links in our documentation. We have created scripts that you can use to check links across the site after it is built to ensure that any changes that you have made have a valid link target. To install Lychee and run the link checker locally, follow the installation instructions in the Lychee documentation. You can choose the installation approach that is best for you; the options include using a package manager like brew or scoop, installing from GitHub or building from source using Cargo.

To check internal links, for example, links between different pages on the site or image references, run:

npm run link-check-offline

This is the same test that is run in CI; it should pass before your contributions are merged.

You can also check all links, including links to external resources like other websites:

npm run link-check

Caution

Checking links to online resources will often result in false positives, meaning that some links that work online might appear to be broken. Some sites may reject requests if they don’t appear to be from a browser, or you may be rate-limited. It’s good practice to check each link that Lychee flags as broken before you try to update it.

Add yourself as a contributor

To add yourself to the table of contributors, follow the bot usage instructions.