This guide describes the workflow to contribute to the JSON Schema technical documentation. If you would like to contribute to other aspects of the JSON Schema website, like writing blog articles or publishing a case study, please read the website's Contributing Guide for more details.
Thank you for helping us improve our documentation.
This guide is intended for use by documentation contributors and will help you get started with the basics of our working processes.
To contribute to the JSON Schema documentation you will need to complete the following steps:
- Create a GitHub account, if you don't have one already.
- Read our Code of Conduct.
- Install the JSON Schema website on your computer.
- Read our style guide.
To stay updated with news about the JSON Schema project and its documentation, engage with our team, ask questions, and discuss ideas, please join our Slack workspace. We particularly recommend the following channels:
-
#documentation: Discussions related to the JSON Schema documentation. -
#website: Discussions related to our website. -
#introductions: Self-introductions and connecting with other members of the community. -
#community-announcements: Events and updates related to the JSON Schema project. -
#anouncements: Important announcement from the JSON Schema organization. -
#stack-overflow: Stack overflow questions tagged with JSON Schema.
This is a list of best practices the JSON Schema project strives for and resources we recommend for additional information:
- File and branching naming conventions: We use dashes instead of spaces, and lowercase letters to name .md files and branches. For example:
implementers-guide.md,web-feat-diataxis. - Commit messages: To learn how to write good commit messages, see Step-by-step guide on how to write good commit messages on Git.
Here we describe three ways you can help us improve our documentation:
- Review pull requests
- Work on an existing issue
- Propose changes
Are you new to the JSON Schema community? Help us review pull requests. Reviewing pull requests helps you familiarize yourself with our workflows, learn how others contribute, and understand the project's needs and goals. It's a great way to start contributing and you'll be better prepared to make your own contributions.
To work on an existing issue, go to the JSON Schema docs board and check all the open issues.
If the issue you select has no assignees, you can claim the issue by assigning it to yourself and tag @json-schema-org/docs-team in the comments to let us know you'll be working on it.
If the issue you select has already an assignee, write a comment expressing your interest in collaborating with them. The JSON Schema respects the order in which people claim issues, therefore, you will have to check if the assignee is accepting collaborations.
After you have been assigned to an issue, fork the json-schema-org/website repository and create a new branch from main to work on the changes.
To propose modifications to our documentation that do not have an issue in the documentation board, you can create a GitHub issue and use the Documentation template to describe the changes. After that, you can decide whether you want to work on the changes yourself or let someone else claim the issue. If you decide to work on the issue, assign it to yourself and commit the changes to a new branch.
To submit your work to review by the community, open a draft pull request to the main upstream branch, and add the issue your pull request solves. Add @json-schema-org/docs-team as a reviewer of your pull request, and let us know in the #documentation Slack channel your pull request is ready for review.
The reviewers might ask for additional changes. When they approve your pull request, you can merge your changes into main and your contribution to the project will be complete!
We created this guide based on templates from The Good Docs Project.