Migrations/bookorbit
1
0
Fork 0
mirror of https://github.com/bookorbit/bookorbit.git synced 2026-11-03 00:11:37 -06:00
Code Issues Packages Projects Releases Wiki Activity

docs: fix contributing guide links

Browse Source 
Fixes #1994
This commit is contained in:
neon
2026-10-30 00:51:26 +00:00
parent fd1aac3074
commit 805a857776
6 changed files with 22 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/COMMUNITY.md
+1 -1
View File
@@ -33,4 +33,4 @@ Do not report security vulnerabilities in public issues. Follow the private repo
- If a conversation produces actionable work, create a linked bug report or feature request and keep the community conversation available for context. An idea being discussed does not mean it is approved for implementation.
- Other inactive issues, including help requests, receive a stale warning after 60 days and close after another 14 days without activity. If help is still needed, leave an update before closure or request reopening afterward. Maintainers can use `pinned` to exempt a topic from stale closure.
Before implementing a change, follow the approval and assignment process in [CONTRIBUTING.md](CONTRIBUTING.md). Those requirements apply to code contributions, not to asking for help or joining a conversation.
Before implementing a change, follow the approval and assignment process in [CONTRIBUTING.md](../CONTRIBUTING.md). Those requirements apply to code contributions, not to asking for help or joining a conversation.
docs/CONTRIBUTING.md
-287
View File
@@ -1,287 +0,0 @@
# Contributing to BookOrbit
Thanks for your interest in contributing to BookOrbit. Whether you are fixing a typo or building a major feature, this guide walks you through the process from start to finish.
**Companion docs:**
- [DEVELOPMENT.md](DEVELOPMENT.md) - Local setup, architecture, commands, and technical reference.
- [TESTING.md](TESTING.md) - Test architecture, E2E suites, coverage thresholds, and harness details.
- [COMMIT_GUIDELINES.md](COMMIT_GUIDELINES.md) - Commit message format, types, scopes, and examples.
- [LOCALIZATION.md](LOCALIZATION.md) - User-facing copy, ICU messages, Crowdin, and adding languages.
---
## Where to Start
For usage questions, setup help, or community conversations, see the [community guide](COMMUNITY.md). You do not need approval or assignment to ask a question or participate.
Not sure what to work on? Look for issues tagged with:
- [`good first issue`](../../labels/good%20first%20issue) - Scoped tasks with clear acceptance criteria. Great for your first contribution.
- [`help wanted`](../../labels/help%20wanted) - Larger tasks where maintainer bandwidth is limited.
If nothing there catches your eye, browse the open issues or propose something new.
### Documentation Contributions
Doc improvements are always welcome and have a lighter process:
- No tests required.
- Use a branch name that starts with `BO-<issue-number>-` (e.g. `BO-456-docs-fix-setup-instructions`).
- Focus areas: fixing inaccuracies, improving examples, adding missing guides, clarifying confusing sections.
The rest of this guide still applies (issue first, PR template, etc.), but expect a faster review cycle.
---
## Security Issues
Do **not** open public issues for security vulnerabilities. Use GitHub's [private vulnerability reporting](https://github.com/bookorbit/bookorbit/security/advisories/new) instead. See [SECURITY.md](../.github/SECURITY.md) for details.
---
## Contribution Workflow
This is the end-to-end journey from idea to merged PR. Each phase builds on the previous one.
### Phase 1: Find or Create an Issue
> **Issue first, PR second.** Every pull request must link to an approved issue assigned to the
> contributor. PRs without prior approval and assignment will be closed without review.
- Browse [open issues](../../issues) for something you want to tackle.
- Report a problem using the [bug report](https://github.com/bookorbit/bookorbit/issues/new?template=bug_report.yml) form, or propose a concrete improvement using the [feature request](https://github.com/bookorbit/bookorbit/issues/new?template=feature_request.yml) form.
- For setup or usage questions, use [Question / Help](https://github.com/bookorbit/bookorbit/issues/new?template=question.yml).
- Not sure if your idea fits the roadmap? Start a [Community Discussion](https://github.com/bookorbit/bookorbit/issues/new?template=discussion.yml) before investing time.
### Phase 2: Get Maintainer Approval
Before writing code, comment on the issue to say that you want to implement it and briefly describe
your proposed approach. Then wait for both:
- A maintainer comment explicitly approving the implementation.
- A maintainer assigning the issue to you.
Do not start implementation or open a pull request, including a draft, until both have happened. A
reaction or lack of a response does not count as approval.
If nobody responds within seven days, leave one polite follow-up comment and @mention the maintainers
or contributors already involved in the issue. People have responsibilities outside the project and
may simply have missed the original notification, so a reminder is welcome. Continue waiting for an
explicit reply before starting implementation or opening a pull request.
This step prevents wasted effort on changes that conflict with the project direction. Small bug fixes
with clear reproduction are usually approved quickly.
### Phase 3: Fork and Clone
[Fork the repository](../../fork), then clone your fork:
```bash
git clone https://github.com/<your-username>/bookorbit.git
cd bookorbit
git remote add upstream https://github.com/bookorbit/bookorbit.git
```
> **Trusted contributors** with direct push access can skip the fork and work on branches in the main repository. The rest of this guide assumes the fork workflow.
### Phase 4: Set Up Your Environment
If this is your first time:
```bash
pnpm setup
```
This handles everything: dependencies, PostgreSQL, migrations, and seed data. See [DEVELOPMENT.md](DEVELOPMENT.md) for prerequisites, manual setup steps, and troubleshooting.
### Phase 5: Create Your Branch
Always branch from the latest `main`:
```bash
git fetch upstream
git checkout -b BO-<issue-number>-<short-description> upstream/main
```
Branch name requirements:
- Start with `BO-<issue-number>-`
- Use lowercase kebab-case for the description suffix
- Example: `BO-123-fix-reader-sync`
### Phase 6: Implement Your Change
Start the dev server and get to work:
```bash
pnpm dev
```
Refer to [DEVELOPMENT.md](DEVELOPMENT.md) for architecture details, project structure, database workflows, and conventions. A few ground rules:
- **One logical change per PR.** Do not bundle a bug fix with a refactor or unrelated cleanup.
- **No unapproved dependencies.** Propose new dependencies in the linked issue first (see [Adding Dependencies](#adding-dependencies)).
- **Keep the scope tight.** If you discover something unrelated that needs fixing, open a separate issue for it.
#### Localizing User-Facing Text
BookOrbit uses Vue I18n, with English as the complete source catalog and Crowdin as the source of truth for every other language.
- Add every new user-facing message, including accessibility labels and transient states, to `client/src/locales/en.json` and reference it through Vue I18n.
- Do not add the key or an English fallback to any non-English catalog. Target catalogs are intentionally sparse, and missing messages fall back to English at runtime.
- Do not create or improve target-language translations in a feature pull request. Translate them in [Crowdin](https://crowdin.com/project/bookorbit); the controlled translation workflow will open a separate PR.
- Run `pnpm --filter client validate:locales` after changing `en.json`.
- Read [LOCALIZATION.md](LOCALIZATION.md) before changing ICU plural structure, changing the meaning of an existing message, or adding a language.
CI rejects edits to existing non-English catalogs in ordinary pull requests. A deliberate new-language setup may add only an empty target catalog until Crowdin export is enabled.
### Phase 7: Write and Run Tests
Testing expectations depend on what you changed:
| Change type | What is expected |
| ----------------------- | ---------------------------------------------- |
| Bug fix | Regression test proving the bug is fixed |
| New backend feature/API | Server unit tests for the new behavior |
| New frontend logic | Client unit tests (composables, utilities) |
| UI-only change | Screenshots, plus a recording for interactions |
| Refactor | Existing tests stay green, no new tests needed |
Run the full test suite:
```bash
pnpm test
```
If your change touches an area covered by an existing E2E suite, run it locally before pushing: `pnpm run e2e:run -- <suite-id>`. Use `pnpm run e2e:list` to see available suites.
For E2E tests, suite IDs, coverage thresholds, and the test harness, see [TESTING.md](TESTING.md).
### Phase 8: Verify Code Quality
The project has two automated gates that catch issues before they reach CI:
- **Pre-commit hook** runs `lint-staged` on your staged files (ESLint + Prettier).
- **Pre-push hook** runs `pnpm verify:fast` (lint + typecheck + tests). Your push is blocked if this fails.
Before marking your PR ready for review, run the full quality gate yourself:
```bash
pnpm verify
```
See the [Code Quality](DEVELOPMENT.md#code-quality) section in DEVELOPMENT.md for individual commands.
### Phase 9: Commit Your Work
Follow the format in [COMMIT_GUIDELINES.md](COMMIT_GUIDELINES.md). The short version:
```
<type>(<scope>): <summary>
```
- **Type:** `feat`, `fix`, `db`, `perf`, `refactor`, `style`, `docs`, `test`, `build`, `ci`, `chore`, `security`, `revert`
- **Scope** (optional): `auth`, `books`, `library`, `metadata`, `kobo`, `scanner`, etc.
- **Summary:** Imperative mood, lowercase, no period. Describe what the commit does, not what you did.
Examples: `feat(kobo): add shelf sync endpoint`, `fix(reader): correct page count for multi-volume PDFs`
### Phase 10: Open a Pull Request
Push your branch and open a PR against `main`:
```bash
git push origin BO-123-your-feature-name
```
When creating the PR:
- **Fill out the PR template.** It asks for the linked approval, a summary, the commands you ran with
their real output, what you did while manually testing, end-to-end evidence, and an authorship note
covering any AI assistance.
- **Use a Conventional Commit-style PR title** (for example: `fix(reader): correct page count for multi-volume PDFs`).
- **Link your issue** with a GitHub closing keyword in the description (`close`, `closes`, `closed`, `fix`, `fixes`, `fixed`, `resolve`, `resolves`, `resolved`) and an issue reference (`#123` or `owner/repo#123`).
Example:
```md
## What changed
Correct page count handling for multi-volume PDFs.
Fixes: #123
```
- **Open as a draft** if the implementation is incomplete after the linked issue has been approved and
assigned. Use the issue for direction before approval.
- **Attach end-to-end evidence.** Upload a recording showing the changed behavior through the real
client. Ready-for-review PRs without the required evidence will not be reviewed.
- **Disclose AI usage** if applicable. See [AI_POLICY.md](AI_POLICY.md) for the format and expectations.
### Phase 11: Respond to Review
- Expect feedback within a few days, sometimes sooner.
- Push additional commits to address review comments. Do not force-push during review unless a reviewer asks you to.
- Do not resolve review threads yourself. Let the reviewer confirm the fix.
- If feedback is unclear, ask for clarification in the thread.
### Phase 12: After Merge
Your changes ship in a future release when maintainers cut one. Keep your fork in sync for your next contribution:
```bash
git fetch upstream
git checkout main
git merge upstream/main
git push origin main
```
---
## Quick-Reference Checklist
Before marking your PR ready for review, confirm:
- [ ] Linked to an approved issue
- [ ] Branch is up to date with `main`
- [ ] One logical change per PR
- [ ] `pnpm verify` passes locally
- [ ] Tests included per the [testing expectations table](#phase-7-write-and-run-tests)
- [ ] Full-stack behavior manually validated
- [ ] UI changes include screenshots, plus a recording when behavior or interaction changed
- [ ] User-facing text uses keys added only to `client/src/locales/en.json`; non-English catalogs are unchanged
- [ ] PR template fully completed
- [ ] No unintended files (build artifacts, `.env`, personal configs)
- [ ] No unapproved new dependencies
---
## Policies
### Adding Dependencies
Do not add dependencies without prior discussion in the linked issue. If proposing one, document:
- What problem it solves.
- Why existing dependencies or a small custom implementation are insufficient.
- Maintenance status and community activity of the package.
### Breaking Changes and Self-Hosted Upgrades
BookOrbit is self-hosted. Any change that can break existing deployments must include a clear upgrade path before merge.
If your PR introduces a breaking change (schema, API contract, environment variable, config format):
- Call it out explicitly in the PR description.
- Document the required upgrade steps.
- Include Drizzle migrations for schema changes. Never hand-write migration SQL.
### AI-Assisted Contributions
See [AI_POLICY.md](AI_POLICY.md). The short version: disclose all AI usage in your PR description and make sure you understand every line of the diff.
---
## License
By submitting a contribution, you license it under the [GNU Affero General Public License, version 3 only](../LICENSE), together with the [BookOrbit Additional Terms](../ADDITIONAL_TERMS.md). You represent that you have the authority to grant this license. Copyright in your contribution remains yours.
docs/DEVELOPMENT.md
+2 -2
View File
@@ -2,7 +2,7 @@
Everything you need to work in this codebase: architecture, setup, workflows, conventions, and commands.
For the contribution process (issues, PRs, review), see [CONTRIBUTING.md](CONTRIBUTING.md). For localization and Crowdin workflow details, see [LOCALIZATION.md](LOCALIZATION.md). For test architecture and E2E suite details, see [TESTING.md](TESTING.md).
For the contribution process (issues, PRs, review), see [CONTRIBUTING.md](../CONTRIBUTING.md). For localization and Crowdin workflow details, see [LOCALIZATION.md](LOCALIZATION.md). For test architecture and E2E suite details, see [TESTING.md](TESTING.md).
---
@@ -105,7 +105,7 @@ git clone https://github.com/<your-username>/bookorbit.git
cd bookorbit
```
If you are an external contributor, fork first and clone your fork. See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
If you are an external contributor, fork first and clone your fork. See [CONTRIBUTING.md](../CONTRIBUTING.md) for details.
#### Step 2 - Create your environment file
docs/TESTING.md
+1 -1
View File
@@ -8,7 +8,7 @@ BookOrbit has three layers of tests:
Each layer has a specific job and its own tooling. Do not test the same behavior at multiple layers.
For testing expectations by change type, see [CONTRIBUTING.md](CONTRIBUTING.md).
For testing expectations by change type, see [CONTRIBUTING.md](../CONTRIBUTING.md).
For the development setup, see [DEVELOPMENT.md](DEVELOPMENT.md).
---