docs: add in-repository documentation in doc/ and link from README#1
docs: add in-repository documentation in doc/ and link from README#1andybrown668 wants to merge 1 commit intomainfrom
Conversation
Add doc/README.md (index), doc/architecture.md, doc/development.md, doc/configuration.md. Update README.md to link to doc/ and to docs.rustfs.com; fix CONTRIBUTING.md development guide link to doc/development.md. Creation metadata (extended description): - Created by: Cursor AI assistant (Auto / agent router). - Cost: Not available in this context; check Cursor session usage or billing for token/API cost of this edit session. Made-with: Cursor
There was a problem hiding this comment.
Pull request overview
Adds a new doc/ directory with in-repo documentation and updates top-level docs links so contributors/users can find architecture, development, and configuration guidance directly in the repository.
Changes:
- Add in-repository documentation pages under
doc/(index + architecture/development/configuration). - Update
README.mdto link both in-repo docs and the external docs site. - Fix
CONTRIBUTING.mdto point to the new in-repo development guide.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| doc/README.md | Adds an index page for in-repo documentation. |
| doc/architecture.md | Summarizes workspace layout and major crate/component areas. |
| doc/development.md | Documents build/test/pre-commit workflows and relevant Make targets. |
| doc/configuration.md | Documents env-var naming conventions and links to config sources. |
| README.md | Adds links to doc/ alongside external docs. |
| CONTRIBUTING.md | Updates development guide link to the new in-repo path. |
| ## Environment Variables | ||
|
|
||
| - **Naming**: Use flat `RUSTFS_*` names (e.g. `RUSTFS_REGION`, `RUSTFS_ADDRESS`, `RUSTFS_VOLUMES`). Do not use module-segmented names like `RUSTFS_CONFIG_*`. | ||
| - **Constants and conventions**: See [crates/config/src/constants/](../crates/config/src/) and [crates/config/README.md](../crates/config/README.md) (including environment variable naming). |
There was a problem hiding this comment.
The link text points to crates/config/src/constants/, but the actual link target is ../crates/config/src/, which doesn’t match. Update the URL to point at the src/constants/ directory (or adjust the link text) so readers land on the intended location.
| - **Constants and conventions**: See [crates/config/src/constants/](../crates/config/src/) and [crates/config/README.md](../crates/config/README.md) (including environment variable naming). | |
| - **Constants and conventions**: See [crates/config/src/constants/](../crates/config/src/constants/) and [crates/config/README.md](../crates/config/README.md) (including environment variable naming). |
| - Format: `cargo fmt --all` and `cargo fmt --all --check` | ||
| - Lint: `cargo clippy --all-targets --all-features -- -D warnings` | ||
| - Check: `cargo check --all-targets` | ||
| - Tests: `cargo test --all-targets` | ||
|
|
There was a problem hiding this comment.
In the “Typical steps” list, the test command is cargo test --all-targets, but make test in this repo excludes e2e_test and also runs doc tests. Consider updating this line to match the Makefile behavior so the documented manual steps align with the project’s quality gates.
| ```bash | ||
| # Run tests | ||
| make test | ||
| # or | ||
| cargo test --all-targets | ||
| ``` |
There was a problem hiding this comment.
The suggested manual test command (cargo test --all-targets) isn’t equivalent to make test in this repo: the Make target excludes the e2e_test crate and adds doc tests. Consider updating the “or” command to mirror the Makefile fallback (cargo test --workspace --exclude e2e_test … plus doc tests) to avoid surprising long-running or environment-dependent tests.
Type of Change
Related Issues
N/A
Summary of Changes
Add in-repository documentation in
doc/and link from README.doc/README.md(index),doc/architecture.md,doc/development.md,doc/configuration.md.README.mdto link todoc/and to docs.rustfs.com.CONTRIBUTING.mddevelopment guide link todoc/development.md.Checklist
make pre-commitImpact
Additional Notes
Single-commit PR split from
andy/documentationfor easier review.Verification:
make pre-commitThank you for your contribution! Please ensure your PR follows the community standards (CODE_OF_CONDUCT.md) and sign the CLA if this is your first contribution.