CONTRIBUTING.md
Rama main · réplica de lectura del repositorio original.
# Contributing to TinaCMS
The following is a set of guidelines and tips for contributing to the TinaCMS and its packages.
## Contributor License Agreement
Before a Pull Request can be accepted, all contributors must sign the [Contributor License Agreement](https://cla-assistant.io/tinacms/tinacms). A GitHub Action runs against all Pull Requests to ensure that **all commit authors** on the associated Pull Request have signed the agreement. The contributor license agreement helps us ensure that the code being contributed was written by the contributor and that we have proper license to use the contribution.
## Getting started
Currently this is a monorepo built with Turborepo and PNPM
You _should_ :fingers_crossed: be able to just run these commands. (Please make a note of any hang-ups you ran into during this process and feel free to update this doc with any tips you have for others.)
> [!TIP] We recommend using [fnm](https://github.com/Schniz/fnm) or [nvm](https://github.com/nvm-sh/nvm) to switch Node versions automatically
> Having issues? Feel free to reach out on [Discord](https://discord.com/invite/zumN63Ybpf)
```sh
# check the node version, the .nvmrc file lists the required version
node -v
# install pnpm via corepack
corepack enable
# ensure you have the correct version (check version number in package.json)
pnpm -v
# install dependencies
pnpm install
# build all the packages
pnpm run build
# watch all packages
pnpm run watch
# in a separate tab, navigate to starter project
cd examples/next/kitchen-sink
# start the dev server
pnpm run dev
```
Now you should be able to navigate to http://localhost:3000 and see the starter project.
## Reporting Bugs
Before filing a new bug report:
- **Search existing issues** first — there is a good chance it is already known
- **For TinaCMS bugs:** open a new issue via [the bug report template](https://github.com/tinacms/tinacms/issues/new?template=bug-report.yml)
- **For TinaCloud bugs or general questions:** start in the [TinaCMS Discord](https://discord.com/invite/zumN63Ybpf) `#ask-for-help` channel — the post guidelines there enforce the same checklist
- **For security vulnerabilities:** never file publicly. See [`SECURITY.md`](SECURITY.md) for the private disclosure path.
The bug report template (`.github/ISSUE_TEMPLATE/bug-report.yml`) asks for a description of the bug and your environment (including any custom adapters or non-default setup), and encourages the exact error message, repro steps and a reproduction repo. The same checklist is published at https://tina.io/docs/contributing/bug-reports.
If you are using an AI assistant (Claude Code, Cursor, etc.) to draft an issue, point it at `.github/ISSUE_TEMPLATE/bug-report.yml` so the formatting matches the form's H3 sections.
## Picking up an issue
- **Looking for a first task?** Issues labelled [`onboarding`](https://github.com/tinacms/tinacms/labels/onboarding) are small, well-scoped and suited to people new to the project.
- **Check for a linked PR first.** Look at the issue's **Development** sidebar. If a PR is already open, comment there instead of starting a second one.
- **You don't need to wait to be assigned.** Comment on the issue that you're picking it up, then open a draft PR early. That stops two people doubling up and gets you maintainer feedback sooner.
- **Commit with the right email.** The [CLA check](#contributor-license-agreement) runs on every commit author in the PR, so commit with an email linked to the GitHub account that signed it.
- **Got a question?** Ask in the [TinaCMS Discord](https://discord.com/invite/zumN63Ybpf).
## PR Workflow
All pull requests should include a changeset. To create a changeset, ensure you don't have any uncommitted changes and then run the following command:
```sh
# from the root of the repo
pnpm changeset
```
Choose the package or packages that were affected by your work. _(Tip: you may have to wait a couple of seconds after selecting your packages, sometimes it doesn't get registered and it'll ask you to pick again)_
> Note: You do not need to select packages which _depend_ on changes you made in other packages, the release process will do this automatically for you later on. Just choose packages you worked on directly.
Choose the _type_ of version change they should get. Skipping `major` will ask you if you want to select `minor`, if you skip that it will assume `patch`.
> Note: If you're not sure what to choose, `patch` is usually a safe bet.
Proceed through the prompts until you have a new `.md` file in the `.changeset` directory. It'll look [like this](https://github.com/tinacms/tina-graphql-gateway/blob/348ef1e57e2e61fb9896d616aabc6f3c85d37140/.changeset/pretty-sloths-return.md)
Feel free to edit this file if you want to alter your messages or which versions will be bumped.
### Commit your changes and push to GitHub and create a PR
The PR will be checked for a changeset file. You're done!
Once the PR is merged and has completed it's actions, you can install the changes by installing the @dev version of the package. So if there were changes to `@tinacms/graphql` merged into `main`, you can test them out by running `pnpm add @tinacms/graphql@beta`.
However, your changes won't yet be published to NPM under the `@latest` tag yet. So without specifying the `@beta` tag, users won't get your latest changes. Instead, when the PR is merged to `main`, another action will kick in. It will create a _separate_ PR which is essentially all of the active changesets in flight. So several merged PRs may result in several pending changesets.
This PR calls `pnpm changeset version`, which _deletes_ changeset files and updates `CHANGELOG.md` files in each package. This PR will stay up to date as new changesets enter the `main` branch. [Here's an example](https://github.com/tinacms/tina-graphql-gateway/pull/316) of what that looks like. Only once this PR is merged will the latest changes be generally available.
### For maintainers: Merge the "Version Packages" PR _back_ to `main`
Previous PRs to main would _not_ have triggered NPM packages to be published because their `versions` haven't been bumped. That's the purpose of the "Version Package" action. So these merges will now have updated `versions`, resulting in publishes to NPM.
## Creating a dev release (core team only)
Ensure you have created a changeset and have a clean `git` working directory.
Build your changes with `pnpm build`
Run `pnpm version:snapshot`
Re-pin internal deps so the snapshot publishes exact versions (pnpm would otherwise expand `workspace:^` to a caret prerelease range, which npm can resolve to a different snapshot batch):
```sh
for f in packages/*/package.json packages/@tinacms/*/package.json; do
sed 's/"workspace:\^"/"workspace:*"/g' "$f" > "$f.tmp" && mv "$f.tmp" "$f"
done
```
Run `pnpm publish:dev`
If you have 2FA, this will prompt you to enter you one-time code for each package you publish.
Run `git checkout -- .` This will clear out the versioning changes.
---
## Trying out changes to a package
### Local
If the changes affect local use of the packages (i.e. not the ContentAPI), use one of the example apps (e.g. `examples/next/kitchen-sink`).
To use a **tinacms** repository cloned locally, when running your application, use the `--rootPath` flag:
```
node tinacms/packages/@tinacms/cli/bin/tinacms dev --rootPath {{ APPLICATION PROJECT PATH }}
```
e.g. `node tinacms/packages/@tinacms/cli/bin/tinacms dev --rootPath ~/Developer/tina/examples/next/kitchen-sink`
Then inside another terminal (in the tinacms project), run:
```
pnpm watch
```
> ### Warning
>
> This will only work for packages loaded by webpack. That means that environments which don't use
> webpack (i.e. SSR builds) will not use this alias
## Error handling
When code needs to react to _which_ error occurred, do not match the raw
message string (for example `error.message.includes('already exists')`). Message
prose is not a contract, so rewording it silently breaks every consumer.
- **In-repo errors:** import the identifier from `@tinacms/schema-tools`
(`src/errors.ts`) and build the thrown message from it. Producers and consumers
reference the same constant, so they cannot drift.
- **Structured codes beat fragments:** where an error carries a discriminant
field, switch on the code rather than the text. See `EDITORIAL_WORKFLOW_ERROR`
in `packages/tinacms/src/toolkit/form-builder/editorial-workflow-constants.ts`.
- **External-service strings** (TinaCloud, esbuild, Cloudinary) still get a named
constant, marked as an un-enforceable contract since this repo does not own the
producer.
- **Security-tied messages** (for example `ERR_PATH_TRAVERSAL`) must keep their
user-visible bytes stable. Update the asserting tests if you ever change one.
See [#6777](https://github.com/tinacms/tinacms/issues/6777) for background.
## Windows
### Symlinks
The kitchen-sink example projects (`examples/next/kitchen-sink`, `examples/astro/kitchen-sink`, `examples/react/kitchen-sink`) share content and public assets from a central `examples/shared/` directory. This avoids duplicating files across framework examples.
The shared structure:
- `examples/shared/content/` — all content files (authors, blogs, global, pages, posts, tags)
- `examples/shared/public/` — all public assets (uploads, blocks)
**Content** is shared via TinaCMS's `localContentPath` config option — each project's `tina/config.tsx` sets `localContentPath: '../../../shared'` so TinaCMS reads content directly from `examples/shared/`. No symlinks are used for content directories (TinaCMS's path traversal security checks reject symlinks that resolve outside the project root).
**Public assets** (`public/uploads`, `public/blocks`) are shared via directory symlinks to `examples/shared/public/`, since these are served by the web framework (not TinaCMS).
On macOS and Linux, symlinks work automatically. On Windows, git defaults to creating text files instead of real symlinks, which will break the public asset symlinks.
To clone with symlink support:
```sh
git clone -c core.symlinks=true <repo-url>
```
Or enable symlinks on an existing clone:
```sh
git config core.symlinks true
git checkout -- .
```
Windows requires [Developer Mode](https://learn.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development) enabled for symlinks to work.
### cross-env
Scripts that set environment variables use `cross-env` for Windows compatibility. Windows `cmd` does not support the Unix `VAR=value command` syntax, so `cross-env` ensures environment variables are set correctly across all platforms.
## E2E tests
In order to run the Playwright E2E tests locally:
Please refer to the readme file in playwright/tina-playwright