--- url: https://docs.codefox.ai/contribute/make-a-change.md --- # Make a change and open a pull request This page takes you from an idea to a pull request that the checks have passed, and explains what happens to it after that. ## Before you start * Your machine builds and tests the app you want to change. See [Set up a development machine](/contribute/development-setup). * For a bug, look for an existing issue first, or open one with the repository's **Bug** form. It asks which app, your version (the output of `foxden version`, or the build shown in the app's settings) and what happened. Use invented data only. * A security problem never goes in an issue or a pull request. Follow the repository's security policy instead; the issue forms link to it. ## Make the change 1. Fork the repository and clone your fork. 2. Create a branch from an up-to-date `main`: ```bash git fetch origin git switch -c fix-library-export origin/main ``` 3. Install the app you will change and the shared code, for example for Library: ```bash scripts/bootstrap.sh library ``` 4. Make the change in the smallest place that does the job. Keep to the patterns around it: * Shared behaviour lives once in `packages/shared`: sign-in, access, files, jobs, email, security headers. Use it rather than writing a second copy in an app. See [Repository layout](/contribute/repository-tour). * Screens are built from the components in `packages/brand` (its `llms.txt` lists them). A component the library lacks is added to the library, not written into one app. * Words on screen about levels and sharing come from `packages/shared/src/access/copy.ts`. * An app's agent tools are listed in its `mcp-contract.json`, and a tool or a parameter is never removed or renamed once it ships, so that assistants built on it keep working. A new need is a new tool. * A change to a database adds a migration in the app's migrations folder. 5. Add or change tests that prove the change. 6. Run the checks for what you changed: ```bash scripts/verify.sh ``` It runs the typecheck and unit tests of every app your branch touches. A change to `packages/shared` reaches every app that uses it. When you changed a database query, also run that app's database tests (see [Set up a development machine](/contribute/development-setup)). 7. If you changed a page of this site, run its check in `docs/portal`: ```bash npm run check ``` ## Open the pull request 1. Push your branch to your fork. 2. Open a pull request against `main`. Say what the change does and why, how you tested it, and, for a change to a screen, what it looks like. 3. List any new file your change adds (see the next section). The pull request's checks start by themselves. For each app in `scripts/_products.sh`, they install it with `scripts/bootstrap.sh` and run `scripts/verify.sh` on Ubuntu, on GitHub's own runners with a read-only token and no secrets. One check, `checks`, is green when every app is. When a check is red, open its log, fix the cause, and push again. The checks run again on each push. ## After the checks pass The public repository is published from Foxden's source repository: every few hours on weekdays, an export copies the source's `main` into it. A change is accepted by landing it on the source's `main`, and the next export brings it here. On the source repository, a change lands through a merge queue (`.github/workflows/land.yml`). The queue builds the commit `main` would hold with the change in it and checks that commit: the verify workflow of each row of `scripts/_products.sh` the change reaches (typecheck, unit tests, database tests and the build), and a rule for every file the change adds. A change that fails is taken out of the queue with a comment that names what failed. ### New files need a rule The export publishes only files listed in the source repository's `tools/public-repo/policy.json`: a file is either included, or excluded with a reason (for example, because it might name a client or an internal host). The merge queue refuses a change that adds a file with no rule. So when your pull request adds a file, name it in the description and say whether it belongs in the public copy. ## Licence Foxden is licensed under the Apache License, Version 2.0 (the `LICENSE` file at the top of the repository). Under that licence, a contribution you submit for inclusion is licensed under the same terms, unless you say otherwise. ## Related * [Repository layout](/contribute/repository-tour) * [Write a docs page](/contribute/write-docs)