Thank you for your interest. FluentCMS is starting over, so there is little to build on yet. See the announcement for the current state.
| Ref | Role |
|---|---|
main |
The default branch. Pull requests into it must pass CI. |
feature/* |
Integration branches for a group of related issues. Issue pull requests into them run fast checks. |
archive/* |
Earlier code, kept for reference. Read-only and not maintained. |
| Path | Role |
|---|---|
docs/planning/ |
The plan: the backend technical specification and the specification it builds on, including the decisions log. |
docs/decisions/ |
Decision records for choices made during implementation. See its README. |
- Every change starts from an issue. For anything beyond a small fix, wait for a maintainer to confirm the approach before writing code.
- Branch from the intended target, named
<issue-number>-<short-slug>, for example2680-contributing-guide. Use the agreedfeature/*branch when the issue belongs to a batch of related work; otherwise usemain. - Open a pull request against that target. Put
Closes #<issue-number>in the description, and keep an issue pull request to its issue. - CI must pass. Pull requests are squash-merged, so the pull request title becomes the commit title. Keep it short and imperative.
The CI workflow builds the whole solution on Linux and runs every test project there in six shards (units with the tool and the client, two of integration tests, two of plugins and host, admin), plus the data jobs, Markdown lint, packaging and the templates job, which installs the dotnet new templates from the packed packages, creates and builds every combination, runs the plugin's tests and starts the SQLite hosts and a PostgreSQL host (templates/test-templates.sh). This runs for every pull request into main and every push to it. The data jobs run the data tests on SQLite and PostgreSQL 15 in every run. SQL Server 2025 joins them on pushes to main, on pull requests from feature/* branches, on pull requests that change a data provider (src/FluentCMS.Data.*), a migration or the data tests, and on the nightly and manual runs, and SQL Server 2019 only on the nightly and manual runs. An issue pull request therefore needs no manual run for SQL Server. Each server runs in two shards, split by namespace. On Windows the same runs build the whole solution and run only the fast tests: the SDK unit, core unit and architecture tests, the admin's component tests (FluentCMS.Admin.Tests), the tool's tests (FluentCMS.Cli.Tests) and the host's commands with export and import on SQLite (the Commands namespace of FluentCMS.Core.IntegrationTests). The full Windows suite runs nightly and on manual runs, so a Windows-only failure shows up in the nightly run rather than on a pull request. A failed nightly run opens an issue titled Nightly CI failed, or adds a comment to it while it is open.
The admin's tests are under admin/tests/. The component tests (FluentCMS.Admin.Tests) run on bUnit 2.15.2 with xUnit v3 and Shouldly and need no browser, so they join the fast checks. The Tests (admin) shard runs them with the API tests (FluentCMS.Admin.ApiTests), which run the admin's client against FluentCmsTestHost and run in full CI only. The end-to-end tests (FluentCMS.Admin.EndToEnd) run in full CI only, in the End-to-end (admin) job: they publish the reference host, run it in Production on SQLite with the Blog sample on a free port of 127.0.0.1 over https with a certificate the run makes, seed it with its own commands, and drive the admin at /admin in Chromium with Playwright 1.64.1. The job downloads Chromium's headless shell on every run, which takes seconds, and fails a skipped test, so a browser that did not install fails the job. A manual run of CI with the traces input keeps a Playwright trace of each failed test in the job's test results, with the network log and response bodies left out and the passwords, tokens, codes and cookies the browser saw masked. The Pack job publishes FluentCMS.Admin.App trimmed, and a trim warning in a FluentCMS assembly fails it.
The Compose workflow builds the image, starts src/FluentCMS.Host/compose.yaml on PostgreSQL and MinIO and runs a smoke test against it (Docker). It runs on pushes to feature/* branches, CI calls it on pushes to main and on manual runs, and pull requests do not run it.
The Fresh machine workflow runs eng/fresh-machine.ps1, the path of a new user from the packages alone: it packs every package into a folder feed and, in a work directory outside the repository, installs the templates and the fluentcms tool from it, makes a Blog host, adds and applies its migrations, makes an administrator and a key, compiles the generated TypeScript, exports the site and imports it into a second host, and builds and tests a plugin. Linux runs it on SQLite and PostgreSQL and then checks that a broken feed fails it, and Windows runs it on SQLite. It runs on pushes to feature/* branches, and CI calls it on pushes to main, on manual runs and on the pull request of a feature branch into main; issue pull requests do not run it. Run it locally with pwsh eng/fresh-machine.ps1, which needs PowerShell 7.4, the .NET SDK and Node.js, takes PostgreSQL with -PostgreSql and -PostgreSqlImport (two empty databases), and keeps its work directory for the logs. -Feed with -Version runs it against packages that are published already, such as nuget.org after a release, and so does a manual run of the workflow with a feed and a version.
The Publish workflow publishes a release from a tag v* on main: the packages to nuget.org, the image to ghcr.io/fluentcms/fluentcms and the GitHub release (releasing). A pull request that changes the packaging, such as a project file under src/ or admin/src/, Directory.Build.props or the Dockerfile, runs it as a dry run, which packs and builds everything, lists what a release would push and pushes nothing. Every package carries one version, from VersionPrefix in Directory.Build.props: builds that are not releases get a pre-release suffix, ci.{run id}.{attempt} in CI and dev locally. A new packable project needs a README.md beside it and a Description, which the Pack job checks. eng/check-packages.cs expects SourceLink to point at the origin of the clone, so on a fork it checks the fork's own repository.
For a batch of related issues, create a branch such as feature/media from main. Each issue branches from it and opens its pull request back into it. The Feature CI workflow builds the whole solution on Linux and Windows and runs the fast tests, the same as the Windows job of CI: SDK unit tests, core unit tests, architecture tests, the admin's component tests, the tool's tests and the host's commands on SQLite, and Markdown lint. The rest of the integration tests, the data, host and plugin tests, packaging and the templates job run in full CI.
Merge the issue pull requests into the feature branch as they pass review and fast checks; enable auto-merge on each as soon as its review is done, so that nobody waits on a check. Keep the heavy steps out of the fast checks: a trimmed publish, a browser test or a job that needs a container belongs in full CI. When the batch is ready, open one pull request from the feature branch into main. The CI workflow automatically runs all test projects on Linux, the fast tests on Windows, the data jobs, Markdown lint, packaging and the templates job. Fix any failures on the feature branch and push again; the full checks rerun. Keep the feature branch current with main and rerun validation after incorporating changes from it. A passing run from before a change does not validate the updated code.
The fast checks have different names from the full checks required by main. Keep main protected by Markdown lint, Build and check (ubuntu-latest), Tests (units), Tests (integration), Tests (plugins), Build and test (windows-latest), Data tests (sqlite), Data tests (postgresql) and Pack. Tests (integration), Tests (plugins) and Data tests (postgresql) are no longer test jobs: the required job reports each name and passes only when every shard of the tests and of the data tests passed, so the protection needs no change when a shard is added. Tests (admin) becomes required when the admin's milestone A0 reaches main, and End-to-end (admin) when A1 does: until then a pull request into main has no such check, so requiring it would block every one. A repository ruleset on feature/** requires Feature markdown lint, Fast checks (ubuntu-latest) and Fast checks (windows-latest) instead, so auto-merge works on pull requests into feature branches too.
To check the combined work before opening the final pull request, go to Actions → CI → Run workflow, choose the feature branch and select Run workflow. This runs the full suite on that branch, including every test project on Windows, whenever needed. Run it once in the middle of a milestone as well, not only at the end, so that a failure in a job the fast checks skip is found while the work that caused it is still open. The workflow must first be present on main for GitHub to show the manual trigger, and the selected branch must contain the updated workflow. Manual runs provide early feedback; the pull request into main still runs its own validation, including the proposed merge with main, but not the full Windows suite.
List the included issues with Closes #<issue-number> in the final pull request into main, so GitHub closes them when the batch reaches the default branch. A pull request targeting a feature branch does not close them on merge.
Every issue has one type:* label. Issues that belong to a part of the codebase also have one area:* label.
| Label | Meaning |
|---|---|
type:feature |
A new capability. |
type:bug |
A defect. |
type:chore |
Repository, tooling or housekeeping. |
type:docs |
Documentation. |
type:epic |
A milestone-level feature, sliced into issues. |
type:adr |
A proposal for an architecture decision. |
type:question |
A question or a request for clarification. |
area:* labels name the part of the codebase: build, sdk, schema, storage, content, publishing, localization, identity, authorization, jobs, events, settings, testing and admin.
Work is planned in milestones, M0 Foundation first. The goal and exit criteria of the backend's milestones, M0 to M7, are in section 8 of the backend technical specification; those of the admin's, A0 onward, in section 9 of the admin technical specification, whose issues are numbered A-nn and labelled area:admin. Each milestone has one tracking issue holding a checklist of its issues, for example #2707 for M0, #2708 for M1 and #3151 for A0. Issues are created milestone by milestone, so later milestones appear when they start. Tick the tracking issue when your pull request merges.
A new NuGet package or GitHub Action is named in its issue, with the version, before it is added, so that it is visible in review. Package versions live in Directory.Packages.props. The pull request that adds the dependency repeats it in a "Dependencies" paragraph.
Workflows pin every action to a full commit SHA, with its version tag in a trailing comment. Dependabot proposes weekly updates for actions and NuGet packages, grouping minor and patch updates per ecosystem. CI fails when a direct or transitive package has a known vulnerability, and deprecated packages only raise a warning.
The description contains, in this order:
Closes #<issue-number>.- A short paragraph on what changes and why.
- A "Dependencies" paragraph naming every new package or GitHub Action with its version, or saying there are none.
- The acceptance list from the issue as a checklist. Tick only what you verified.
- Every pull request is reviewed before it merges. One approval is not required, but a review always happens.
- Review your own diff before opening the pull request and include the fixes in it, so CI validates the reviewed code once instead of again after a follow-up push.
- Every required check must pass. Once the review is done, enable auto-merge with
gh pr merge <number> --auto --squash; GitHub merges the pull request as soon as every required check passes. - Branch protection does not require an issue branch to be up to date with its target. Merge the target into the issue branch only to resolve a conflict.
- Pull requests are squash-merged into a linear history. The title becomes the commit title, so it is short and imperative, for example "Update the contributing guide and add decision records".
You need the .NET 10 SDK, at the version in global.json. The tests use SQLite by default, so no database server is needed and Docker is not required.
To run the data tests on another provider, set FLUENTCMS_TEST_PROVIDER to postgresql, sqlserver-2019 or sqlserver-2025. The tests then start that server once in a container through Testcontainers and give each test a database of its own on it, so they need Docker with Linux containers. Tests of SQLite itself, such as its journal modes, file locking, conventions and query plans, are skipped on the other providers with the reason. Run one provider at a time:
FLUENTCMS_TEST_PROVIDER=postgresql dotnet test --project tests/FluentCMS.Data.Tests -c ReleaseThe S3 and Azure Blob media storage tests run MinIO and Azurite through Testcontainers and need Docker with Linux containers; without it they are skipped, and the test output says why.
The admin's end-to-end tests (admin/tests/FluentCMS.Admin.EndToEnd) need Chromium for Playwright; without it the browser tests are skipped with a message, and the tests of the host they start, which need no browser, still run. They publish the reference host with no build, so build it in the same configuration first, which building the project does. No trust store, certificate store or machine setting is changed: the browser accepts the certificate of the run's own host by its key. On Windows the host imports the run's certificate files with default flags, so their private keys stay in the user's key folder (%APPDATA%\Microsoft\Crypto\Keys) until #3212. To run them, install the browser once with PowerShell, then set FLUENTCMS_E2E_TRACES to a folder to keep a masked trace of each failed test, which npx playwright show-trace opens:
dotnet build admin/tests/FluentCMS.Admin.EndToEnd -c Release
pwsh admin/tests/FluentCMS.Admin.EndToEnd/bin/Release/net10.0/playwright.ps1 install chromium
dotnet test --project admin/tests/FluentCMS.Admin.EndToEnd -c Release --no-buildTo run a host on PostgreSQL, or media on S3, compose.yaml starts PostgreSQL 15 and MinIO at the versions the tests use, on localhost only, with their data in volumes. It is for development, not production. The passwords default to fluentcms; set FLUENTCMS_POSTGRES_PASSWORD and FLUENTCMS_MINIO_PASSWORD to change them. PostgreSQL takes its password when it creates the volume, so set it before the first start or delete the volume.
docker compose up -dThe reference host then runs on PostgreSQL with FluentCms__Database__Provider=PostgreSql, ConnectionStrings__FluentCms=Host=127.0.0.1;Database=fluentcms;Username=fluentcms;Password=fluentcms and FluentCms__Database__MigrateOnStartup=true. The reference host keeps media on the local disk unless FluentCms__Media__S3__* is set; it, or a host of your own that calls media.UseS3, can use MinIO, which answers S3 on http://127.0.0.1:9000 (ForcePathStyle true) and serves its console on http://127.0.0.1:9001, where you create the bucket. docker compose down stops both and keeps the data; add -v to delete it.
During implementation, run the test project or test class affected by the change. Before opening an issue pull request, into a feature branch or main, run the fast checks once:
dotnet build -c Release -warnaserror
dotnet test --project tests/FluentCMS.Sdk.Tests -c Release --no-build
dotnet test --project tests/FluentCMS.Core.Tests -c Release --no-build
dotnet test --project tests/FluentCMS.Architecture.Tests -c Release --no-build
dotnet test --project admin/tests/FluentCMS.Admin.Tests -c Release --no-build
dotnet test --project tests/FluentCMS.Cli.Tests -c Release --no-build
dotnet test --project tests/FluentCMS.Core.IntegrationTests -c Release --no-build --filter-namespace "FluentCMS.Core.IntegrationTests.Commands*" --minimum-expected-tests 40
npx --yes markdownlint-cli2 "**/*.md"CI runs the full suite, so there is no need to run it locally for an issue pull request. Run the full checks to reproduce a CI failure, or before opening the pull request from a feature branch into main:
dotnet build -c Release -warnaserror
dotnet test -c Release --no-build
dotnet pack -c Release --no-build -o artifacts/packages
dotnet run eng/check-packages.cs -- artifacts/packages 1.0.0-dev
dotnet publish admin/src/FluentCMS.Admin.App -c Release --no-build -o artifacts/admin
dotnet run eng/check-admin-size.cs -- artifacts/admin 3500000
npx --yes markdownlint-cli2 "**/*.md"Publish the admin into an empty folder: files left from an earlier publish count toward the size check. The budget is the one of the Pack job in .github/workflows/ci.yml.
A test that hangs is named in the diagnostic log of its test app: xUnit.net reports each test that runs longer than two minutes (tests/xunit.runner.json), and --timeout fails the tests still running with the stack of the call they wait in, if they wait on the test's cancellation token. CI writes the log for every test project and prints these lines when a test job fails or is cancelled. A hang outside a test body, such as a class or collection fixture whose InitializeAsync never returns, is not named: it gets no long-running report, and --timeout ends the run without a name or a stack. To get the lines locally:
dotnet test --project tests/FluentCMS.Plugins.Search.Tests -c Release --timeout 10m --diagnostic --diagnostic-verbosity Information --diagnostic-output-directory artifacts/test-resultsThe plan lives in docs/planning/. When implementation needs a choice that the decisions log and the backend specification do not already settle, record it in docs/decisions/ as a short decision record. Open an issue labelled type:adr to propose it. The README there has the details and the template.
Commits and pull requests are authored by the person who submits them. Do not add tool-generated co-author trailers or "generated by" footers. You are responsible for what you submit, whatever tools you used to write it.