You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING-docs.md
+21-15Lines changed: 21 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,21 +1,24 @@
1
1
# Docs Contributing Guide
2
2
3
-
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](https://github.com/json-schema-org/website/blob/main/CONTRIBUTING.md) for more details.
3
+
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](https://github.com/json-schema-org/website/blob/main/CONTRIBUTING.md) for more details.
4
4
5
5
## Welcome
6
+
6
7
Thank you for helping us improve our documentation.
7
8
8
9
This guide is intended for use by documentation contributors and will help you get started with the basics of our working processes.
9
10
10
11
## Before you start
12
+
11
13
To contribute to the JSON Schema documentation you will need to complete the following steps:
12
14
13
15
1.[Create a GitHub account](https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github), if you don't have one already.
14
16
2. Read our [Code of Conduct](https://json-schema.org/overview/code-of-conduct).
15
17
3.[Install the JSON Schema website](https://github.com/json-schema-org/website/blob/main/INSTALLATION.md) on your computer.
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](https://json-schema.org/slack). We particularly recommend the following channels:
20
23
21
24
-`#documentation`: Discussions related to the JSON Schema documentation.
@@ -29,60 +32,63 @@ To stay updated with news about the JSON Schema project and its documentation, e
29
32
-`#anouncements`: Important announcement from the JSON Schema organization.
30
33
31
34
-`#stack-overflow`: Stack overflow questions tagged with JSON Schema.
32
-
35
+
33
36
## Best practices
34
37
35
38
This is a list of best practices the JSON Schema project strives for and resources we recommend for additional information:
36
39
37
40
1. 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`.
38
41
2. Commit messages: To learn how to write good commit messages, see [Step-by-step guide on how to write good commit messages on Git](https://www.freecodecamp.org/news/how-to-write-better-git-commit-messages/).
39
42
40
-
## Contribution workflow
43
+
## Contribution workflow
41
44
42
45
Here we describe three ways you can help us improve our documentation:
43
46
44
-
45
47
1. Review pull requests
46
-
2. Work on an existing issue
47
-
3. Propose changes
48
+
2. Work on an existing issue
49
+
3. Propose changes
48
50
49
51
### Review pull requests
50
52
51
-
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.
53
+
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.
52
54
53
55
### Work on an existing issue
54
56
55
-
To work on an existing issue, go to the [JSON Schema docs board](https://github.com/orgs/json-schema-org/projects/16) and check all the open issues.
57
+
To work on an existing issue, go to the [JSON Schema docs board](https://github.com/orgs/json-schema-org/projects/16) and check all the open issues.
56
58
57
-
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.
59
+
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.
58
60
59
61
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.
60
62
61
-
After you have been assigned to an issue, fork the [json-schema-org/website](https://github.com/json-schema-org/website) repository and create a new branch from `main` to work on the changes.
63
+
After you have been assigned to an issue, fork the [json-schema-org/website](https://github.com/json-schema-org/website) repository and create a new branch from `main` to work on the changes.
62
64
63
65
### Propose changes
64
66
65
-
To propose modifications to our documentation that do not have an issue in the [documentation board](https://github.com/orgs/json-schema-org/projects/16), you can [create a GitHub issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-an-issue#creating-an-issue-from-a-repository) 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.
67
+
To propose modifications to our documentation that do not have an issue in the [documentation board](https://github.com/orgs/json-schema-org/projects/16), you can [create a GitHub issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-an-issue#creating-an-issue-from-a-repository) 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.
66
68
67
69
## Add metadata to newly created markdown files
70
+
68
71
Metadata helps organize content and maintain consistency across all pages in the documentation. It also provides key information about the file, such as its title, author, and the last updated date.
69
72
70
73
When contributing to the documentation, it is essential to include metadata in every new markdown file. Metadata is critical for successfully building and rendering the file locally. Without it, the file may fail to render correctly or cause errors in the documentation system.
71
74
72
75
### Example of metadata in a new markdown file
73
-
Every new `.md` file should start with a YAML front matter block. Here's an example:
74
-
---
76
+
77
+
## Every new `.md` file should start with a YAML front matter block. Here's an example:
78
+
75
79
title: "Your Page Title"
76
80
section: "docs" # Can be used to categorize the content
77
81
date: "YYYY-MM-DD" # Optional: Date when the page was created or last updated
78
82
author: "Your Name" # Optional: Your name if you're the author
79
83
tags: ["tag1", "tag2"] # Optional: Tags to categorize the page
84
+
80
85
---
86
+
81
87
To add the front matter metadata, copy and paste the example above at the top of your .md file and replace the details with the information of your document.
82
88
83
89
## Create a Pull Request
84
90
85
-
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.
91
+
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.
86
92
87
93
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!
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+8-15Lines changed: 8 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,6 +5,7 @@ First off, thanks for taking the time to contribute! 🫶
5
5
All types of contributions are encouraged and valued. See the [Table of Contents](#table-of-contents) for different ways to help and details about how this project handles them. Please make sure to read the relevant section before making your contribution. It will make it much easier for us maintainers and smooth out the experience for all involved. The community looks forward to your contributions. 🎉
6
6
7
7
If you don't have time to contribute, that's fine. There are other easy ways to support the project and show your appreciation:
8
+
8
9
- Star the project on Github
9
10
- Post on X or Linkedin about JSON Schema `#jsonschema
10
11
@@ -26,7 +27,6 @@ If you don't have time to contribute, that's fine. There are other easy ways to
26
27
- ⌨️ [Pull requests](#%EF%B8%8F-pull-requests)
27
28
- 🏛 [License](#-license)
28
29
29
-
30
30
## 🌱 Code of Conduct
31
31
32
32
Before making your first contribution, please ensure you are familiar with our [Code of Conduct](https://github.com/json-schema-org/.github/blob/main/CODE_OF_CONDUCT.md).
@@ -47,7 +47,7 @@ Please use our issues templates that provide hints on what information we need t
47
47
48
48
### 🛠️ Add a new Implementation
49
49
50
-
To add a new implementation, please open a PR, adding the details of your implementation to `\pages\implementations\main.md` file. We also invite you to join the discussion in `#implementers` channel in our [Slack workspace](https://json-schema.org/slack).
50
+
To add a new implementation, please open a PR, adding the details of your implementation to `\pages\implementations\main.md` file. We also invite you to join the discussion in `#implementers` channel in our [Slack workspace](https://json-schema.org/slack).
51
51
52
52
### ✍️ Publish a blog post
53
53
@@ -61,11 +61,11 @@ To publish a case study, we encourage you to join `#adopters` channel in our [Sl
61
61
62
62
### 📋 Improving the Documentation
63
63
64
-
Want to help us improve the JSON Schema documentation? Check out our [docs Contributing guide](https://github.com/json-schema-org/website/blob/main/CONTRIBUTING-docs.md) for docs and Style guide. These documents will give you the basics of our processes to get you started and text-formatting guidelines to create consistent documentation for JSON Schema.
64
+
Want to help us improve the JSON Schema documentation? Check out our [docs Contributing guide](https://github.com/json-schema-org/website/blob/main/CONTRIBUTING-docs.md) for docs and Style guide. These documents will give you the basics of our processes to get you started and text-formatting guidelines to create consistent documentation for JSON Schema.
65
65
66
66
### 🌐 Improving the Website
67
67
68
-
If you would like to join the efforts to improve the JSON Schema Website, we encourage you to check our [website contribution board](https://github.com/orgs/json-schema-org/projects/11) to get a sense of the pending issues and bugs and who is doing what. We also invite you to join the discussion in `#website` channel in our [Slack workspace](https://json-schema.org/slack).
68
+
If you would like to join the efforts to improve the JSON Schema Website, we encourage you to check our [website contribution board](https://github.com/orgs/json-schema-org/projects/11) to get a sense of the pending issues and bugs and who is doing what. We also invite you to join the discussion in `#website` channel in our [Slack workspace](https://json-schema.org/slack).
69
69
70
70
### 🎨 Improving the Design
71
71
@@ -80,7 +80,6 @@ If you would like to contribute to our CI/CD pipeline, we encourage you to revie
80
80
We value contributions to our testing efforts. Here are ways you can help improve our test coverage and quality:
81
81
82
82
1.**Writing Tests**: If you're adding new features or fixing bugs, please include relevant tests. We use Cypress for both end-to-end (E2E) and component testing.
83
-
84
83
- For new components, add component tests in the `cypress/components` directory.
85
84
- For new features or bug fixes affecting user interactions, add E2E tests in the `cypress/e2e` directory.
86
85
@@ -89,6 +88,7 @@ We value contributions to our testing efforts. Here are ways you can help improv
89
88
3.**Test Documentation**: Help improve our testing documentation, making it easier for new contributors to understand and write tests.
90
89
91
90
4.**Running Tests**: Before submitting a pull request, ensure all tests pass by running:
91
+
92
92
```
93
93
yarn cypress:run:all
94
94
```
@@ -97,7 +97,6 @@ We value contributions to our testing efforts. Here are ways you can help improv
97
97
98
98
For more details on our testing setup and how to run tests, please refer to the Testing section in our [INSTALLATION.md](./INSTALLATION.md#testing) file.
99
99
100
-
101
100
### ⌨️ Pull requests
102
101
103
102
We welcome pull requests for editorial suggestions and resolving open issues.
@@ -111,26 +110,20 @@ We strongly encourage linking every pull request to an existing issue. If no cor
111
110
112
111
Generally, pull requests should be made to the `main` branch.
113
112
114
-
Most PRs, will be left open for a minimum of 14 days. Minor fixes may be merged more quickly once approved by a project member.
113
+
Most PRs, will be left open for a minimum of 14 days. Minor fixes may be merged more quickly once approved by a project member.
115
114
116
115
### Markdown Style Guide
117
116
118
117
Contributors to our Docs or our Blog can have a look at the [custom markdown style guide](https://json-schema.org/md-style-guide) with a list of useful markdown tags providing tools to easily create cool content that provides a better user experience.
119
118
120
119
## Triage
121
120
122
-
Please check the [triage process](https://github.com/json-schema-org/.github/blob/main/TRIAGE.md) to learn how we review and label incoming issues .
121
+
Please check the [triage process](https://github.com/json-schema-org/.github/blob/main/TRIAGE.md) to learn how we review and label incoming issues .
123
122
124
123
## Feedback
125
124
126
125
Feedback on this process can be made informally through our [Slack server](https://json-schema.org/slack) and formally using our [Community Discussions](https://github.com/json-schema-org/community/discussions).
127
126
128
-
## References
127
+
## References
129
128
130
129
This document was adapted from [https://contributing.md](https://contributing.md/)!
Copy file name to clipboardExpand all lines: INSTALLATION.md
+20-9Lines changed: 20 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -30,18 +30,20 @@ This guide provides step-by-step instructions for installing the JSON Schema Web
30
30
-[Prerequisites](#prerequisites)
31
31
-[Steps](#steps)
32
32
33
-
34
33
## Setting up Project
35
34
36
35
## Configuration
37
36
38
37
### Requirements
38
+
39
39
Use the following tools to set up the project:
40
40
41
41
Node.js v20.9.0+
42
42
43
43
### Cloning the repository
44
+
44
45
This project uses git submodules, so you will need to run the following commands to fully clone the repo.
46
+
45
47
```
46
48
git submodule init
47
49
git submodule update
@@ -52,9 +54,11 @@ git submodule update
52
54
This step is optional. Environment variables are not required to run the website on your local development server.
53
55
54
56
1. Create a new `.env` file by copying the contents of the `.env.example` into `.env` file. Use this command:
57
+
55
58
```
56
59
cp .env.example .env
57
60
```
61
+
58
62
2. Open .env and fill in your actual values for each variable.
59
63
60
64
3. Save the file.
@@ -69,7 +73,6 @@ This project uses modern Yarn ([email protected]), which requires Corepack for proper s
69
73
70
74
Corepack is an experimental tool to help with managing versions of your package managers. It exposes binary proxies for each supported package manager that, when called, will identify whatever package manager is configured for the current project, download it if needed, and finally run it.
71
75
72
-
73
76
#### Installing Corepack
74
77
75
78
If you're using Node.js version 14.19.0 or later, Corepack is included but might need to be enabled. For Node.js 16.10 or later, Corepack is available by default but might still need to be enabled.
@@ -129,30 +132,33 @@ For more information about Corepack, refer to the [official Node.js documentatio
129
132
### Installing Dependencies
130
133
131
134
Install dependencies
135
+
132
136
```
133
137
yarn
134
138
```
135
139
136
140
### Running the Development Server
137
141
138
142
Run the development server on http://localhost:3000
143
+
139
144
```
140
145
yarn dev
141
146
```
142
147
143
148
### Building Static Files
144
149
145
150
Build static files on `/out` folder
151
+
146
152
```
147
153
yarn build
148
154
```
155
+
149
156
## Testing
150
157
151
158
We use Cypress for both end-to-end (E2E) testing and component testing. This document will guide you through the process of running tests and generating coverage reports.
152
159
153
160
### Running Tests
154
161
155
-
156
162
#### Opening Cypress Test Runner
157
163
158
164
To open the Cypress Test Runner, which allows you to run tests interactively, use:
@@ -200,6 +206,7 @@ yarn test:coverage:all
200
206
```
201
207
202
208
This command will:
209
+
203
210
1. Run E2E tests with coverage
204
211
2. Run component tests with coverage
205
212
3. Merge the coverage results
@@ -251,6 +258,7 @@ yarn run lint:fix
251
258
This project uses Husky to run checks for the formatting, linting, typecheck and build commands before committing the code.
252
259
253
260
#### pre-commit hook
261
+
254
262
pre-commit hook will run the following commands:
255
263
256
264
```
@@ -260,6 +268,7 @@ yarn run build
260
268
```
261
269
262
270
If you don't want these pre-commit checks running on each commit, you can manually opt out of it using the `--no-verify` flag with your commit message as shown:-
271
+
263
272
```
264
273
git commit -m "commit message" --no-verify
265
274
```
@@ -275,14 +284,16 @@ If you are a Docker lover, you have the option to use it following these instruc
275
284
After cloning repository to your local, perform the following steps from the root of the repository.
276
285
277
286
#### Steps:
287
+
278
288
1. Build the Docker image:
279
-
```bash
280
-
make install
281
-
```
289
+
290
+
```bash
291
+
make install
292
+
```
282
293
283
294
2. Start the container:
284
-
```bash
285
-
make run
286
-
```
295
+
```bash
296
+
make run
297
+
```
287
298
288
299
Now you're running JSON Schema website in a development mode. Container is mapped with your local copy of the website. Whenever you make changes to the code, the website will refresh and changes visible in `http://localhost:3000`.
0 commit comments