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/.CONTRIBUTING.md
+94-4Lines changed: 94 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,13 +1,36 @@
1
-
# Contribute to the Polkadot Developer Docs
1
+
# Contributing to Polkadot Documentation
2
2
3
-
The documentation source files are written in [Markdown](https://daringfireball.net/projects/markdown) and generally follow the [PaperMoon style guide](https://github.com/papermoonio/documentation-style-guide/blob/main/style-guide.md). If the PaperMoon style guide doesn't provide explicit guidance on a particular subject, please default to the [Google developer documentation style guide](https://developers.google.com/style).
3
+
Welcome! We're excited that you want to contribute to the Polkadot developer documentation. This guide will help you get started and ensure a smooth contribution experience.
4
4
5
-
This guide covers how to contribute to the documentation, including serving a local version of the site, adding new pages and directories, managing images and code snippets, and a few SEO tips.
5
+
## Quick Start for Contributors
6
+
7
+
**New to contributing?** Start here:
8
+
9
+
1.**Fork the repository** and create a branch for your changes
10
+
2.**Choose your review preference**: Let us know if you'd prefer to handle formatting and style reviews yourself, or if you'd like our team to take over to expedite the process
11
+
12
+
The documentation source files are written in [Markdown](https://daringfireball.net/projects/markdown) and follow the [PaperMoon style guide](https://github.com/papermoonio/documentation-style-guide/blob/main/style-guide.md). For topics not covered by PaperMoon, we default to the [Google developer documentation style guide](https://developers.google.com/style).
- Follow the [style guide](https://github.com/papermoonio/documentation-style-guide/blob/main/style-guide.md)
64
+
- Test your changes locally (see [Viewing Site Locally](#viewing-site-locally))
65
+
66
+
3.**Generate Updated AI Documentation**
67
+
After making content changes, regenerate the AI-ready documentation files:
68
+
```bash
69
+
python scripts/generate_llms_standard.py
70
+
```
71
+
This updates the `llms.txt` and `llms-full.txt` files that power our AI-ready documentation.
72
+
73
+
4.**Create Pull Request**
74
+
- Push your branch and create a pull request
75
+
- Use the PR template to indicate your review preference
76
+
- Include a clear description of your changes
77
+
78
+
5.**Review Process Choice**
79
+
In your pull request, please let us know:
80
+
-**Option A**: "I have time to handle formatting and style review feedback myself"
81
+
-**Option B**: "Please have the Polkadot docs team take over for formatting review to expedite the process"
82
+
83
+
**If choosing Option B**: You must also enable "Allow edits from maintainers" when creating your PR (this option appears for PRs from forks). This allows our team to create a follow-up branch and handle style/formatting changes, letting you focus on the technical content.
84
+
85
+
### Hand-off Process (Internal Team Workflow)
86
+
87
+
When a contributor chooses Option B or becomes unresponsive during review:
88
+
89
+
1.**Create Intermediary Branch**: Create a new branch named `follow-up/PR-[original_pr_number]`
90
+
2.**Redirect Original PR**: Change the destination of the original PR to the intermediary branch
91
+
3.**Complete Formatting Review**: Perform style and formatting reviews on the intermediary branch
92
+
4.**Final Merge**: Merge the completed intermediary branch into master
93
+
94
+
## Generating AI-Ready Documentation
95
+
96
+
When you modify content in the documentation, you should regenerate the AI-ready files to keep them current:
97
+
98
+
### Prerequisites
99
+
- Python 3.x installed
100
+
- Required Python packages (run `pip install -r requirements.txt` in the project root)
101
+
102
+
### Generate llms.txt Files
103
+
```bash
104
+
cd /path/to/polkadot-docs
105
+
python scripts/generate_llms_standard.py
106
+
```
107
+
108
+
This script will:
109
+
- Generate `llms.txt` - A structured index of all documentation pages
110
+
- Generate `llms-full.txt` - Full content of all documentation pages
111
+
- Create category-specific files in the `llms-files/` directory
112
+
113
+
The generated files are automatically included in pull requests and help power AI tools that work with Polkadot documentation.
114
+
25
115
## Viewing Site Locally
26
116
27
117
You may want to spin up a local version of the documentation site to preview your changes. This guide will cover the steps needed to serve a local version.
0 commit comments