wehub-resource-sync
118 lines
5.5 KiB
Markdown
118 lines
5.5 KiB
Markdown
# Contributing
|
|
|
|
Thanks for improving OpenSquilla. Keep pull requests small, focused, and covered by tests that outside contributors can run without private access.
|
|
|
|
## Target Branch
|
|
|
|
Open pull requests against `main` by default. OpenSquilla now uses `main` as the active integration branch for feature work, bug fixes, tests, documentation, and contributor changes.
|
|
|
|
Use `release/*`, `hotfix/*`, `staging/*`, `integration/*`, `sandbox-*`, or a
|
|
maintainer-approved staging/collaboration label only when maintainers request a
|
|
temporary collaboration branch. When in doubt, target `main`.
|
|
|
|
## Linked Issues
|
|
|
|
Declare issue relationships in pull request descriptions with GitHub keywords:
|
|
|
|
- Use `Fixes #123`, `Closes #123`, or `Resolves #123` when the pull request is intended to fix the issue.
|
|
- Use `Refs #123` when the pull request is related but should not move the issue toward closure.
|
|
- Use `None` when no public issue is linked.
|
|
|
|
OpenSquilla keeps issue closure tied to the default branch. Merging a fixing
|
|
pull request into `main` removes the linked-pull-request marker so the issue
|
|
can follow GitHub's normal closing flow. Maintainers may use `has-linked-pr`
|
|
while work is still under review. If a linked pull request is closed without
|
|
merging, the automation removes `has-linked-pr`.
|
|
|
|
## Reporting Bugs
|
|
|
|
Use the bug-report issue template. Attach a diagnostics bundle
|
|
(`opensquilla bundle`, or the Web UI / desktop download button — see
|
|
`docs/troubleshooting.md`); it is redacted by default and safe to share. Quote
|
|
any `(ref: …)` code from the error message you saw. For suspected
|
|
vulnerabilities use SECURITY.md instead.
|
|
|
|
## Attribution On Squash Or Replay
|
|
|
|
When maintainer cleanup, replay, or squash merging collapses contributor
|
|
commits, keep the final non-empty commit attributable with `Co-authored-by:`
|
|
trailers for every human contributor whose work is included. Preserve pull
|
|
request author attribution and commit author attribution separately when they
|
|
differ.
|
|
|
|
If an older squash, replay, or follow-up pull request dropped contributor
|
|
attribution, do not rewrite protected branch history only to repair it. Open a
|
|
focused attribution repair pull request instead: update `CONTRIBUTORS.md` or the
|
|
release notes with affected pull requests and evidence, and include
|
|
`Co-authored-by:` trailers on the repair commit for missing human contributors
|
|
when GitHub can associate those emails. Do not treat "already appears in GitHub
|
|
contributors" as complete repair; that confirms global account representation,
|
|
not attribution for the specific squashed or replayed work.
|
|
|
|
## Default Checks
|
|
|
|
Install development dependencies:
|
|
|
|
```powershell
|
|
uv sync --extra dev --extra recommended
|
|
```
|
|
|
|
Run the public quality gate before opening a pull request:
|
|
|
|
```powershell
|
|
uv run ruff check src tests
|
|
uv run pytest -q
|
|
uv build --wheel
|
|
```
|
|
|
|
Default tests must be offline, deterministic, credential-free, and safe for forks. Do not add network, provider, browser, or channel requirements to the default pull request path.
|
|
|
|
## Test Expectations
|
|
|
|
Add or update public regression tests for behavior changes and bug fixes. Prefer focused unit or integration tests unless the behavior crosses the gateway, browser UI, provider, or channel boundary.
|
|
|
|
Live checks are maintainer-only gates. The `Live Release E2E` workflow covers real provider, browser, and optional channel smoke tests with GitHub secrets and explicit opt-in inputs.
|
|
|
|
## Private Materials
|
|
|
|
Private test suites, release red-team prompts, real provider transcripts, real channel identifiers, local paths, credentials, and AI session artifacts must not be committed.
|
|
|
|
Local maintainer-only files may live under `tests/_private/` or `.omx/private-golden/`; both are excluded from the public tree and default pytest collection.
|
|
|
|
## Third-Party Origins
|
|
|
|
Declare any third-party origin in the pull request. If no third-party material is
|
|
involved, say `none`. If there is any uncertainty, use the more conservative
|
|
category and let maintainers narrow it during review.
|
|
|
|
- `inspired-by`: only the idea influenced the change; no code, rules, fixtures,
|
|
structure, or copied text is reused.
|
|
- `adapted/ported`: OpenSquilla re-expresses upstream behavior, rules, or
|
|
structure in OpenSquilla code.
|
|
- `vendored`: upstream source is copied into the repository with minimal or no
|
|
changes.
|
|
- `direct dependency`: OpenSquilla depends on an external package through
|
|
`pyproject.toml` or another package manager.
|
|
- `modified upstream`: vendored upstream source is patched or otherwise changed
|
|
in the OpenSquilla tree.
|
|
|
|
For `adapted/ported`, `vendored`, and `modified upstream` material, include the
|
|
upstream URL, license, copyright notice, and any required changes to
|
|
`THIRD_PARTY_NOTICES.md` or a local provenance file in the same pull request.
|
|
For direct dependencies, note the package name and license so maintainers can
|
|
audit redistribution and release-bundle obligations.
|
|
|
|
Permissive licenses such as Apache-2.0, MIT, MIT-0, BSD, ISC, and compatible
|
|
public-domain-equivalent grants are usually acceptable. GPL, AGPL, LGPL, SSPL,
|
|
source-available, custom commercial, or unclear licenses require explicit
|
|
maintainer approval before code, rules, fixtures, or adapted implementations are
|
|
merged.
|
|
|
|
## Security Reports
|
|
|
|
Do not include vulnerability details, exploit steps, credentials, or provider tokens in public issues. Use the process in `SECURITY.md` for suspected vulnerabilities.
|
|
|
|
## Community Standards
|
|
|
|
Keep discussion technical, specific, and respectful. The expected conduct for issues, pull requests, and maintainer decisions is documented in `CODE_OF_CONDUCT.md`.
|