CONTRIBUTING.md
Rama main · réplica de lectura del repositorio original.
# Contributing
Contributions are welcome - code, docs, whatever it might be! If this is your first contribution to an Open Source project or you're a core maintainer of multiple projects, your time and interest in contributing to this project is most welcome.
## Read the developers guide
The main documentation site has a [developer guide](https://docs.postmill.ai/developer-docs/). That guide provides you a good understanding of the project structure, and how to setup your development environment. Read this document after you have read that guide. This document is intended to provide you a good understanding of how to submit your first contribution.
## Discuss your contribution first
Before submitting a large contribution, please open a [GitHub Discussion](https://github.com/postmill-ai/postmill-app/discussions) or an issue. This helps us evaluate whether your contribution is a good fit for the project — and saves you time if it isn't. We will review your idea and get back to you as soon as possible.
## Sign the Contributor License Agreement (CLA)
Before we can merge your contribution, you must agree to our Contributor License Agreement (CLA). This documents the rights you grant us and helps ensure that Postmill can always remain Free and Open Source Software.
- Contributing as an individual? The [Individual Contributor License Agreement (ICLA)](./ICLA.md) applies.
- Contributing on behalf of a company or other legal entity? The [Entity Contributor License Agreement (CCLA)](./CCLA.md) applies.
You accept the agreement by sending your written acceptance by email to [legal@postmill.ai](mailto:legal@postmill.ai), referencing the applicable agreement (ICLA or CCLA) as described in those files. You only need to do this once, and it covers your present and future contributions to Postmill.
## Write code with others
This is an open source project, with an open and welcoming community that is always keen to welcome new contributors. We recommend the two best ways to interact with the community are:
- **GitHub issues**: To discuss more slowly, or longer-written messages.
- **[GitHub Discussions](https://github.com/postmill-ai/postmill-app/discussions)**: To ask questions and get quicker feedback.
As a general rule;
- **If a change is less than 3 lines**: You're probably safe just to submit the change without a discussion. This includes typos, dependency changes, and quick fixes, etc.
- **If a change is more than 3 lines**: It's probably best to discuss the change in an issue or on discord first. This is simply because you might not be aware of the roadmap for the project, or understand the impact this change might have. We're just trying to save you time here, and importantly, avoid you being disappointed if your change isn't accepted.
## Types of Contributions
Contributions can include:
- **Code improvements:** Fixing bugs or adding new features.
- **Documentation updates:** Enhancing clarity or adding missing information.
- **Feature requests:** Suggesting new capabilities or integrations.
- **Bug reports:** Identifying and reporting issues.
## AI
To ensure the quality and maintainability of the codebase, **we do not accept Pull Requests generated primarily by AI tools** (e.g., ChatGPT, GitHub Copilot, Claude Code, etc.).
All contributions must be the original work of the author. We reserve the right to close any PR that appears to be AI-generated without further review.
## How to contribute
This project follows a Fork/Feature Branch/Pull Request model. If you're not familiar with this, here's how it works:
1. **Fork the project:** Create a personal copy of the repository on your GitHub account.
2. **Clone your fork:** Bring a copy of your fork to your local machine.
```bash
git clone https://github.com/YOUR_USERNAME/postmill-app.git
```
3. **Create a new branch**: Start a new branch for your changes
```bash
git checkout -b feature/your-feature-name
```
4. **Make your changes**: Implement the changes you wish to contribute.
5. **Push your changes**: Upload your changes to your fork.
```bash
git push -u origin feature/your-feature-name
```
6. **Create a pull request**: Propose your changes **to the main branch**.
# Releasing
Releases are tag-driven; nothing is published from a laptop. Never `git push --tags` — push tags by
name so stale local tags can't fire a workflow.
**App release** (container image + GitHub Release):
1. Add a `## [X.Y.Z] - YYYY-MM-DD` section to `CHANGELOG.md` and set `version.txt` to `vX.Y.Z`; merge.
2. `git tag vX.Y.Z && git push origin vX.Y.Z`. `build-containers.yml` refuses a tag that doesn't
match `version.txt`, pushes `ghcr.io/postmill-ai/postmill-app:vX.Y.Z` and `:latest`, smoke-tests
the image, and creates the release with the digest and a `docker save` tarball attached.
3. Verify: `gh release view vX.Y.Z` and `docker pull ghcr.io/postmill-ai/postmill-app:vX.Y.Z`.
**SDK release** (`@postmill-ai/postmill-sdk`, versioned independently):
1. Bump `version` in `apps/sdk/package.json` and the version line in `docs/developer-docs/sdk.md`; merge.
2. Optional rehearsal: Actions → *Publish SDK* → *Run workflow* with `dry_run` on.
3. `git tag sdk-vX.Y.Z && git push origin sdk-vX.Y.Z`. `publish-sdk.yml` gates the tag against
`package.json`, publishes to npm with provenance and to GitHub Packages, and creates the release.
**One-time setup** (must be in place before the first run of each workflow):
- npm auth is OIDC trusted publishing, so there is no `NPM_TOKEN` secret: on npmjs.com the package's
*Trusted Publisher* names this repository and the workflow file `publish-sdk.yml`.
- A GHCR package first pushed by Actions is private; make it public once under the package's
settings so self-hosters can pull anonymously.
# Need Help?
Again, do check the [developer guide](https://docs.postmill.ai/developer-docs/). Much of what you probably need to know is in there.
If you encounter any issues, please check the [documentation](https://docs.postmill.ai) or open a GitHub Discussion. Your contributions help make Postmill better!