|
1 | | -# RustFS Documentation Contribution Guide |
| 1 | +# RustFS Documentation |
2 | 2 |
|
3 | | -Welcome to the RustFS community! We really appreciate your interest in contributing to our documentation. Your contribution, whether it's fixing a typo or translating an entire guide, is important to us. This guide aims to provide you with clear instructions to help you smoothly participate in the co-construction of RustFS documentation. |
| 3 | +RustFS is an S3-compatible distributed object storage engine written in Rust. This repository hosts the official VitePress documentation site. Use this guide to understand the layout, add or update content, and keep the docs build passing. |
4 | 4 |
|
5 | | -<p align="center"> |
6 | | -English | |
7 | | - <a href="https://github.com/rustfs/docs.rustfs.com/blob/main/README_ZH.md">简体中文</a> | |
8 | | - <a href="https://github.com/rustfs/docs.rustfs.com/blob/main/README_JA.md">日本語</a> | |
9 | | - <a href="https://github.com/rustfs/docs.rustfs.com/blob/main/README_DA.md">Deutsch</a> | |
10 | | - <a href="https://github.com/rustfs/docs.rustfs.com/blob/main/README_FR.md">Français</a> | |
11 | | - <a href="https://github.com/rustfs/docs.rustfs.com/blob/main/README_TR.md">Türkçe</a> | |
12 | | - <a href="https://github.com/rustfs/docs.rustfs.com/blob/main/README_ES.md">Español</a> | |
13 | | - <a href="https://github.com/rustfs/docs.rustfs.com/blob/main/README_KO.md">한국어</a> | |
14 | | - <a href="https://github.com/rustfs/docs.rustfs.com/blob/main/README_PT.md">Português</a> | |
15 | | - <a href="https://github.com/rustfs/docs.rustfs.com/blob/main/README_RU.md">Русский</a> |
16 | | -</p> |
| 5 | +## Quick Links |
17 | 6 |
|
18 | | ------- |
| 7 | +- Documentation: <https://docs.rustfs.com> |
| 8 | +- Repo issues: <https://github.com/rustfs/docs.rustfs.com/issues> |
| 9 | +- Product issues & roadmap: <https://github.com/rustfs/rustfs/issues> |
| 10 | +- Contributor playbook: `AGENTS.md` |
19 | 11 |
|
20 | | -### Table of Contents |
| 12 | +## Repository Snapshot |
21 | 13 |
|
22 | | -1. (#1-what-is-rustfs) |
23 | | -2. (#2-our-mission-accessible--secure-data-for-everyone) |
24 | | -3. Your Contribution Journey |
25 | | - - (#31-getting-started-your-first-contribution) |
26 | | - - (#32-translating-the-documentation-adding-a-new-language) |
27 | | -4. (#4-the-technical-workflow) |
28 | | - - Prerequisites |
29 | | - - (#42-local-development-setup) |
30 | | - - (#43-pull-request-pr--commit-guidelines) |
31 | | - - (#44-automated-checks--deployment) |
32 | | -5. Community & Licensing |
33 | | - - Acknowledgements |
34 | | - - Content License |
| 14 | +- `docs/` – Markdown sources; each section has an `index.md` entry point. |
| 15 | +- `docs/sidebar.ts` & `docs/config.ts` – navigation definitions that must be updated whenever you add or rename a page. |
| 16 | +- `.vitepress/` – global site configuration, theme, and shared components. |
| 17 | +- `public/` or `images/` folders beside the relevant doc – store media here and reference via relative paths. |
35 | 18 |
|
36 | | -### 1. What is RustFS? |
| 19 | +## Contribution Paths |
37 | 20 |
|
38 | | -RustFS is a simple, high-performance, distributed object storage solution. It is 100% S3-compatible and released under the Apache 2.0 license, making it a commercially-friendly open-source software. |
| 21 | +### Quick edits on GitHub |
39 | 22 |
|
40 | | -Written entirely in Rust—the modern programming language known for memory safety and exceptional performance 1—RustFS is developed by a global community of talented engineers. It is designed to be a powerful, reliable open-source alternative and can serve as a direct replacement for products like MinIO.2 |
| 23 | +1. Browse to the page on <https://docs.rustfs.com> and click **Edit this page on GitHub**. |
| 24 | +2. Use the inline editor for small fixes (typos, broken links, formatting). |
| 25 | +3. Describe the change briefly, submit a pull request (PR), and link any related issue. |
41 | 26 |
|
42 | | -### 2. Our Mission: Accessible & Secure Data for Everyone |
| 27 | +### Planned work or new content |
43 | 28 |
|
44 | | -We believe that data storage should be affordable, reliable, and secure for everyone, everywhere. |
| 29 | +1. Open/confirm an issue so others see what you are tackling. |
| 30 | +2. Create a topic branch such as `docs/feature-short-title`. |
| 31 | +3. Update only the files relevant to the change, keeping edits focused. |
| 32 | +4. Reflect new pages in both `docs/sidebar.ts` and `docs/config.ts`. |
45 | 33 |
|
46 | | -High-quality, multilingual documentation is central to this mission. It's not just an add-on; it's key to lowering the barrier to entry for users and developers across the globe. When you translate a guide or fix an error, you are directly helping people in different linguistic communities to more easily build robust, cost-effective data infrastructure. Your contributions empower a global audience, collectively enhancing data security and sovereignty. This community-driven approach to knowledge sharing maximizes the project's value and helps us truly realize our vision.4 |
| 34 | +### Translations |
47 | 35 |
|
48 | | -### 3. Your Contribution Journey |
| 36 | +1. Mirror the English structure under `docs/<locale>/...` (for example `docs/ja/installation/index.md`). |
| 37 | +2. Reuse existing frontmatter fields (`title`, `outline`, etc.) so VitePress renders consistently. |
| 38 | +3. Keep screenshots or diagrams in locale-specific `images/` folders where possible. |
| 39 | +4. Note covered languages in the PR description so reviewers can track parity. |
49 | 40 |
|
50 | | -We have designed different pathways for various types of contributors. Whether you want to quickly fix a small issue or systematically translate the entire documentation, you'll find the right guide here. |
| 41 | +## Local Development |
51 | 42 |
|
52 | | -#### 3.1 Getting Started: Your First Contribution |
| 43 | +### Prerequisites |
53 | 44 |
|
54 | | -The easiest way to get started is by making small edits directly through the GitHub web interface. This method requires no local development setup and is perfect for minor changes.6 |
| 45 | +- Node.js 18+ |
| 46 | +- `pnpm` (preferred) or another Node package manager |
| 47 | +- Git |
55 | 48 |
|
56 | | -Simple contributions you can make include: |
| 49 | +### Setup & common commands |
57 | 50 |
|
58 | | -- Fixing typos or grammatical errors. |
59 | | -- Correcting broken links. |
60 | | -- Clarifying confusing sentences or paragraphs. |
61 | | -- Reporting an issue for something you don't know how to fix. |
| 51 | +```bash |
| 52 | +git clone https://github.com/rustfs/docs.rustfs.com.git |
| 53 | +cd docs.rustfs.com |
| 54 | +pnpm install |
62 | 55 |
|
63 | | -**The "5-Minute" Pull Request Process:** |
| 56 | +# Work locally |
| 57 | +pnpm dev # vitepress dev server at http://localhost:5173 |
64 | 58 |
|
65 | | -1. Navigate to the page you want to edit on the documentation site `https://docs.rustfs.com/`. |
66 | | -2. Scroll to the bottom and click the "Edit this page on GitHub" link. |
67 | | -3. This will take you to the corresponding Markdown source file on GitHub. Click the pencil icon (✏️) in the top right to enter edit mode. |
68 | | -4. Make your changes in the text editor. |
69 | | -5. When you're done, scroll to the bottom. In the "Propose changes" section, write a concise commit message, e.g., "Fix typo in installation guide." |
70 | | -6. Click the "Propose changes" button. GitHub will then guide you through the process of creating a pull request. |
71 | | - |
72 | | -This process serves as an excellent "on-ramp for contributors," allowing you to familiarize yourself with our workflow without any complex setup. A successful lightweight contribution is often the first step toward deeper involvement.5 |
73 | | - |
74 | | -#### 3.2 Translating the Documentation: Adding a New Language |
75 | | - |
76 | | -This is the core area where we most need community help. Please follow these steps to add or improve translations. |
77 | | - |
78 | | -**Step 1: Coordinate via GitHub Issues** |
79 | | - |
80 | | -To avoid duplicated work and ensure collaboration, please visit our **[GitHub Issues page](https://github.com/rustfs/rustfs/issues)** before you start translating. |
81 | | - |
82 | | -- **Adding a New Language**: Check if someone else is already working on the language you want to translate. If not, please create a new issue with the title `[i18n] Add <Language> (<lang-code>) Translation`, e.g., `[i18n] Add German (de) Translation`. This helps us track progress and assign ownership.7 |
83 | | -- **Improving an Existing Translation**: If you want to improve an existing translation, find the relevant issue or create a new one detailing the improvements you plan to make. |
84 | | - |
85 | | -**Step 2: Understand the Directory Structure** |
86 | | - |
87 | | -Our documentation site is built with VitePress, which uses a file-based directory structure to manage multiple languages.9 All source files are located in the |
88 | | - |
89 | | -`docs/` directory. |
90 | | - |
91 | | -``` |
92 | | -docs/ |
93 | | -├── en/ # English (or as the root directory) |
94 | | -│ ├── guide/ |
95 | | -│ │ └── getting-started.md |
96 | | -│ └── index.md |
97 | | -├── ja/ # Japanese |
98 | | -│ ├── guide/ |
99 | | -│ │ └── getting-started.md |
100 | | -│ └── index.md |
101 | | -└──.vitepress/ |
102 | | - └── config.ts # VitePress configuration file |
103 | | -``` |
104 | | - |
105 | | -**Step 3: Add a New Language Pack** |
106 | | - |
107 | | -1. **Fork and clone** the repository to your local machine, then create a new branch. |
108 | | - |
109 | | -2. In the `docs/` directory, create a new folder using the corresponding **ISO 639-1 language code** for your target language. Please refer to the language code table below. |
110 | | - |
111 | | -3. Copy the **entire contents** of `docs/en/` (or the English source files in the root) into your new language folder. This provides you with a complete file structure to translate. |
112 | | - |
113 | | -4. Open the `docs/.vitepress/config.ts` file and add a new entry for your language in the `locales` object. |
114 | | - |
115 | | - For example, to add German (`de`): |
116 | | - |
117 | | - TypeScript |
118 | | - |
119 | | - ``` |
120 | | - //.vitepress/config.ts |
121 | | - import { defineConfig } from 'vitepress' |
122 | | -
|
123 | | - export default defineConfig({ |
124 | | - //... other configs |
125 | | - locales: { |
126 | | - root: { |
127 | | - label: 'English', |
128 | | - lang: 'en' |
129 | | - }, |
130 | | - // Add the new locale config here |
131 | | - de: { |
132 | | - label: 'Deutsch', // Text in the language dropdown |
133 | | - lang: 'de', // HTML lang attribute |
134 | | - link: '/de/', // Link to redirect to |
135 | | - // You can override theme configs for this locale, |
136 | | - // e.g., for navbar and sidebar text. |
137 | | - themeConfig: { |
138 | | - nav: [ |
139 | | - { text: 'Anleitung', link: '/de/guide/getting-started' } |
140 | | - ], |
141 | | - sidebar: { |
142 | | - '/de/guide/': |
143 | | - } |
144 | | - ] |
145 | | - } |
146 | | - } |
147 | | - } |
148 | | - } |
149 | | - }) |
150 | | - ``` |
151 | | - |
152 | | - To help you configure this correctly, the following table explains the purpose of each property in the `locales` object.9 |
153 | | - |
154 | | -| Property | Type | Required | Description | |
155 | | -| ------------- | -------- | -------- | ------------------------------------------------------------ | |
156 | | -| `label` | `string` | Yes | The text that appears in the language selection dropdown menu in the navbar. | |
157 | | -| `lang` | `string` | No | The `lang` attribute for the `<html>` tag. Uses the directory name if not specified. | |
158 | | -| `link` | `string` | No | The link the user is redirected to when selecting this language. Defaults to the locale's root path (e.g., `/ja/`). | |
159 | | -| `title` | `string` | No | Overrides the site's main title for this specific locale. | |
160 | | -| `description` | `string` | No | Overrides the site's main description for this specific locale. | |
161 | | -| `themeConfig` | `object` | No | Locale-specific theme configuration. Used to translate navbar links, sidebar text, etc. | |
| 59 | +# Required before opening a PR |
| 60 | +pnpm build |
162 | 61 |
|
| 62 | +# Optional final check |
| 63 | +pnpm preview |
163 | 64 | ``` |
164 | | -This table is designed to eliminate ambiguity in the configuration, ensuring contributors can get it right the first time and reducing the need for back-and-forth revisions. |
165 | | -``` |
166 | | - |
167 | | -**Step 4: Translate the Content** |
168 | | - |
169 | | -- In your new language directory, open the Markdown files one by one and translate the text content. |
170 | | -- **Important**: Please **do not** translate the following: |
171 | | - - Keys in the frontmatter (e.g., `title:`, `layout:`). |
172 | | - - Any code within code blocks. |
173 | | - - URL links. |
174 | | - - HTML tags. |
175 | | -- Only translate the human-readable text. |
176 | | - |
177 | | -**Step 5: Submit Your Pull Request** |
178 | | - |
179 | | -Once you've finished translating, please follow the(#43-pull-request-pr--commit-guidelines) to submit your contribution, and make sure to link it to the issue you created in Step 1. |
180 | | - |
181 | | -**Language Code Reference** |
182 | | - |
183 | | -To ensure consistency, please use the standard ISO 639-1 codes from the table below.13 |
184 | | - |
185 | | -| Language | ISO 639-1 Code | |
186 | | -| -------------------- | --------------- | |
187 | | -| Chinese (Simplified) | `zh` or `zh-CN` | |
188 | | -| English | `en` | |
189 | | -| Japanese | `ja` | |
190 | | -| German | `de` | |
191 | | -| French | `fr` | |
192 | | - |
193 | | -### 4. The Technical Workflow |
194 | | - |
195 | | -For developers who wish to make more substantial contributions locally (such as adding a new language pack or making extensive changes), please follow this technical workflow. |
196 | | - |
197 | | -#### 4.1 Prerequisites |
198 | | - |
199 | | -Before you begin, please ensure you have the following software installed on your system: |
200 | | - |
201 | | -- **Node.js**: Version `18.x` or higher.14 You can download it from the |
202 | | - |
203 | | - [official Node.js website](https://nodejs.org/). |
204 | | - |
205 | | -- **Package Manager**: We recommend using `pnpm` for efficiency. You can install it globally with `npm install -g pnpm`. Alternatively, you can use `npm` or `yarn`.15 |
206 | | - |
207 | | -- **Git**: A version control system. You can download it from the [official Git website](https://git-scm.com/). |
208 | | - |
209 | | -#### 4.2 Local Development Setup |
210 | | - |
211 | | -Follow this sequence of commands to run the documentation development server locally: |
212 | | - |
213 | | -1. Fork & Clone the Repository |
214 | | - |
215 | | - First, fork this repository on GitHub. Then, clone your fork to your local machine. |
216 | | - |
217 | | - Bash |
218 | | - |
219 | | - ``` |
220 | | - # Replace <YOUR_USERNAME> with your GitHub username |
221 | | - git clone https://github.com/<YOUR_USERNAME>/docs.rustfs.com.git |
222 | | - cd docs.rustfs.com |
223 | | - ``` |
224 | | - |
225 | | -2. Install Dependencies |
226 | | - |
227 | | - Use pnpm to install all required project dependencies. |
228 | | - |
229 | | - Bash |
230 | | - |
231 | | - ``` |
232 | | - pnpm install |
233 | | - ``` |
234 | | - |
235 | | -3. Run the Development Server |
236 | | - |
237 | | - This command will start a local development server with hot-reloading enabled. |
238 | | - |
239 | | - Bash |
240 | | - |
241 | | - ``` |
242 | | - pnpm docs:dev |
243 | | - ``` |
244 | | - |
245 | | -4. Access the Site |
246 | | - |
247 | | - After successful execution, you should see output in your terminal similar to VitePress dev server running at: <http://localhost:5173/>. Open this URL in your browser to see the documentation site. Any changes you make to the Markdown files will be reflected instantly in the browser.15 |
248 | | - |
249 | | -#### 4.3 Pull Request (PR) & Commit Guidelines |
250 | | - |
251 | | -We follow a standardized workflow to ensure code quality and a clean project history. |
252 | | - |
253 | | -- **Branching Strategy** |
254 | | - |
255 | | - - Always create a new branch for your work. Do not commit directly to the `main` branch. |
256 | | - - Use a descriptive branch name, such as `feat/add-german-translation` or `fix/correct-s3-api-typo`.17 |
257 | | - |
258 | | -- Commit Message Convention |
259 | | - |
260 | | - We adhere to the Conventional Commits specification. This helps us automate changelogs and makes the commit history easier to understand. |
261 | | - |
262 | | - - **Format**: `<type>(<scope>): <subject>` |
263 | | - |
264 | | - - **Examples**: |
265 | | - |
266 | | - - `feat(i18n): add initial french translation` |
267 | | - |
268 | | - - `fix(guide): correct typo in getting-started.md` |
269 | | - |
270 | | - - docs(contributing): update local development setup |
271 | | - |
272 | | - This structured approach is a best practice in many mature open-source projects.8 |
273 | | - |
274 | | -- **Submitting a Pull Request** |
275 | | - |
276 | | - 1. Push your branch to your fork: `git push -u origin your-branch-name`. |
277 | | - 2. On GitHub, open a pull request from your fork to the `main` branch of the `rustfs/docs.rustfs.com` repository. |
278 | | - 3. **Link the Issue**: In the PR description, use keywords like `Closes #123` or `Fixes #123` to link the issue you created earlier. This will automatically close the issue when the PR is merged, a key step in our workflow automation.7 |
279 | | - 4. **Write a Clear Description**: Clearly explain **what** you changed and **why**. If your changes are visual, please include before-and-after screenshots.5 |
280 | | - |
281 | | -- **The Review Process** |
282 | | - |
283 | | - - Once you submit a PR, a project maintainer will review it. |
284 | | - - We may request changes. Please don't be discouraged! This is a normal part of collaborative open-source development aimed at improving the quality of contributions. |
285 | | - - Once your PR is approved and all automated checks have passed, a maintainer will merge it. |
286 | | - |
287 | | -#### 4.4 Automated Checks & Deployment |
288 | | - |
289 | | -To ensure the quality and stability of our documentation, we have a fully automated CI/CD (Continuous Integration/Continuous Deployment) pipeline. |
290 | | - |
291 | | -- **Automated Checks**: When you submit a pull request, GitHub Actions will automatically run a series of checks. These checks verify that the documentation site builds successfully and that the code formatting is correct (linting).19 |
292 | | -- **Automated Deployment**: Once your PR is merged into the `main` branch, GitHub Actions will trigger again, automatically building the latest version of the site and deploying it to `https://docs.rustfs.com`. |
293 | | - |
294 | | -By making this process transparent, we aim to build contributor trust in our workflow. You don't need to worry about the deployment details; a successful merge means a successful deployment. This gives you a clear view of the entire lifecycle of your contribution, from submission to publication.19 |
295 | | - |
296 | | -### 5. Community & Licensing |
297 | | - |
298 | | -#### 5.1 Acknowledgements |
299 | | - |
300 | | -The RustFS documentation is built by the community, for the community. We are incredibly grateful to everyone who contributes their time and expertise. |
301 | | - |
302 | | -Every contribution, no matter how small, is highly valued. To fairly and transparently recognize all contributions, we use GitHub's built-in tools. |
303 | 65 |
|
304 | | -You can see a list of all our amazing contributors on the **[Contributors graph](https://github.com/rustfs/docs.rustfs.com/graphs/contributors)**. This automated, scalable approach ensures that every contribution is acknowledged and always up-to-date.22 |
| 66 | +## Authoring Guidelines |
305 | 67 |
|
306 | | -#### 5.2 Content License |
| 68 | +- Follow the structure “context → overview → steps → references” and keep prose concise, active, and reproducible. |
| 69 | +- Spell out a term the first time it appears (for example, “Large Language Model (LLM)”). |
| 70 | +- Cite third-party facts inline and scrub secrets or private configuration values from examples. |
| 71 | +- Use fenced code blocks with language hints (` ```bash `, ` ```rust `) and provide runnable snippets only. |
| 72 | +- When adding assets, include descriptive `alt` text and ensure tables contain a header row. |
307 | 73 |
|
308 | | -All documentation in this project is licensed under the **Creative Commons Attribution 4.0 International License**.23 |
| 74 | +See `AGENTS.md` for the full checklist that governs navigation updates, localization, and release hygiene. |
309 | 75 |
|
310 | | -By contributing to the RustFS documentation project, you agree that your contributions will be released under this license. |
| 76 | +## Pull Request Checklist |
311 | 77 |
|
312 | | -Under this license, you are free to: |
| 78 | +- [ ] `pnpm build` completes without warnings or errors. |
| 79 | +- [ ] Navigation files updated for any new or renamed pages. |
| 80 | +- [ ] Frontmatter validated and relative links confirmed. |
| 81 | +- [ ] Conventional commit message (for example, `docs: add lifecycle guide`). |
| 82 | +- [ ] PR description explains the change, references issues, and includes screenshots when visuals change. |
313 | 83 |
|
314 | | -- **Share** — copy and redistribute the material in any medium or format. |
315 | | -- **Adapt** — remix, transform, and build upon the material for any purpose, even commercially. |
| 84 | +## License |
316 | 85 |
|
317 | | -You must follow these terms: |
| 86 | +Documentation content is released under the [Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/). By contributing, you agree that your submissions use the same license. |
318 | 87 |
|
319 | | -- **Attribution** — You must give **appropriate credit**, provide a link to the license, and **indicate if changes were made**. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.23 |
| 88 | +_Last Updated: 2025-11-08_ |
0 commit comments