Skip to content
GuideForDeveloperWith or without Foxden Admin

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 ​

  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.
    • 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).

  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.

Foxden is open source under Apache-2.0.