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.
- 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
Fork the repository and clone your fork.
Create a branch from an up-to-date
main:bashgit fetch origin git switch -c fix-library-export origin/mainInstall the app you will change and the shared code, for example for Library:
bashscripts/bootstrap.sh libraryMake 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. - Screens are built from the components in
packages/brand(itsllms.txtlists 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.
- Shared behaviour lives once in
Add or change tests that prove the change.
Run the checks for what you changed:
bashscripts/verify.shIt runs the typecheck and unit tests of every app your branch touches. A change to
packages/sharedreaches every app that uses it. When you changed a database query, also run that app's database tests (see Set up a development machine).If you changed a page of this site, run its check in
docs/portal:bashnpm run check
Open the pull request
- Push your branch to your fork.
- 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. - 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.