42 lines
2.1 KiB
Markdown
42 lines
2.1 KiB
Markdown
# Contributing
|
|
|
|
Stash is a collection of small, self-contained public experiments. Keep each change focused and easy to try.
|
|
|
|
## Before you start
|
|
|
|
Search existing issues and pull requests. For a larger idea, explain the problem, intended audience, smallest useful version, and how you would know it works before building it.
|
|
|
|
## Add an experiment
|
|
|
|
1. Create a descriptive directory under experiments/.
|
|
2. Use [the README template](docs/experiment-template.md) to document it.
|
|
3. Add it to [the experiment index](docs/experiments.md).
|
|
4. Include dependency versions, exact run commands, sample input, and expected output where applicable.
|
|
5. Keep generated output and local dependencies out of Git unless they are intentional deliverables.
|
|
6. Identify third-party sources and retain their license notices.
|
|
|
|
## Open a pull request
|
|
|
|
Work on a branch and target main. Explain the purpose, list the changes, and include the commands and results of checks you actually ran. For visual work, include a screenshot and check narrow screens, keyboard navigation, and readable contrast where relevant. If a check was not run, say so. Do not claim CI has passed unless an actual run did.
|
|
|
|
Review the staged diff before publishing:
|
|
|
|
```sh
|
|
git diff --cached --check
|
|
git diff --cached
|
|
```
|
|
|
|
These commands check whitespace and show content; they do not detect all secrets or prove software works.
|
|
|
|
## Public-data checklist
|
|
|
|
- Use synthetic data or material explicitly approved for public release.
|
|
- Remove credentials, session tokens, private correspondence, and personal records from files and screenshots.
|
|
- Check nested files and Git history before importing a project.
|
|
- Preserve copyright and license notices. Ask before importing material whose license or publication permission is unclear.
|
|
- Treat .gitignore as a convenience, not protection for already tracked files.
|
|
|
|
## Collaboration
|
|
|
|
Be specific, respectful, and practical in reviews. Discuss the work, give reproduction steps, and explain trade-offs. Keep speculative features separate from verified behavior. A maintainer reviews and merges changes; opening a PR does not publish a release.
|