Skip to content

Open-source Revit MCP server: let Claude and other AI assistants read and edit BIM models, with human approval on every change.

docs: branch workflow and importable rulesets to protect main (#102)

A. Sam Mohammad4f11e8f7bc90
diff --git a/.github/rulesets/protect-dev.json b/.github/rulesets/protect-dev.json
new file mode 100644
index 0000000..307a1af
--- /dev/null
+++ b/.github/rulesets/protect-dev.json
@@ -0,0 +1,13 @@
+{
+ "name": "Protect dev from deletion and force-push",
+ "target": "branch",
+ "enforcement": "active",
+ "conditions": {
+ "ref_name": { "include": ["refs/heads/dev"], "exclude": [] }
+ },
+ "bypass_actors": [],
+ "rules": [
+ { "type": "deletion" },
+ { "type": "non_fast_forward" }
+ ]
+}
diff --git a/.github/rulesets/protect-main.json b/.github/rulesets/protect-main.json
new file mode 100644
index 0000000..79f1d20
--- /dev/null
+++ b/.github/rulesets/protect-main.json
@@ -0,0 +1,32 @@
+{
+ "name": "Protect main",
+ "target": "branch",
+ "enforcement": "active",
+ "conditions": {
+ "ref_name": { "include": ["~DEFAULT_BRANCH"], "exclude": [] }
+ },
+ "bypass_actors": [
+ { "actor_id": 5, "actor_type": "RepositoryRole", "bypass_mode": "pull_request" }
+ ],
+ "rules": [
+ { "type": "deletion" },
+ { "type": "non_fast_forward" },
+ {
+ "type": "pull_request",
+ "parameters": {
+ "required_approving_review_count": 0,
+ "dismiss_stale_reviews_on_push": false,
+ "require_code_owner_review": false,
+ "require_last_push_approval": false,
+ "required_review_thread_resolution": true
+ }
+ },
+ {
+ "type": "required_status_checks",
+ "parameters": {
+ "strict_required_status_checks_policy": true,
+ "required_status_checks": [{ "context": "ci-success" }]
+ }
+ }
+ ]
+}
diff --git a/docs/dev-workflow.md b/docs/dev-workflow.md
new file mode 100644
index 0000000..6c18032
--- /dev/null
+++ b/docs/dev-workflow.md
@@ -0,0 +1,50 @@
+# Branches and merging
+
+How changes reach `main`, and the habits we keep to a minimum.
+
+## The branches
+
+| Branch | What it is | Who changes it |
+| --- | --- | --- |
+| `main` | What a release is cut from. Always passes CI. | Only through a pull request, never by a direct push. |
+| `dev` | Where finished, green work is combined and tested by the owner before it goes to `main`. | Merge commits from reviewed branches. No force-push. |
+| `feat/…`, `fix/…`, `docs/…` | One change each. | Anyone, through a pull request. |
+
+## The path of a change
+
+1. Work on a branch named for the change. One concern per branch.
+2. Open one pull request. Describe what changed, how it was tested, and what is **UNVERIFIED** (anything that needs a real Revit).
+3. CI (`ci-success`) must pass and review threads must be answered.
+4. A green branch is merged into `dev` with a **merge commit**, not a squash. That keeps the commit ids, so GitHub marks the pull request as merged when `dev` later goes to `main`.
+5. The owner tests `dev` on a real machine. When they are happy, `dev` goes to `main` in one pull request.
+
+## Protecting `main`
+
+The ruleset in [`.github/rulesets/protect-main.json`](../.github/rulesets/protect-main.json) blocks direct pushes, force-pushes and deletion of `main`, and requires:
+
+- a pull request,
+- the `ci-success` check, on a branch that is up to date with `main`,
+- every review thread resolved.
+
+No approving review is required, because there is one maintainer today and a person cannot approve their own pull request. Repository admins can bypass the rules **only while merging a pull request**, not by pushing. The second file, [`protect-dev.json`](../.github/rulesets/protect-dev.json), only stops `dev` being deleted or force-pushed.
+
+To apply them (the repository owner, in GitHub): **Settings → Rules → Rulesets → New ruleset → Import a ruleset**, choose each file, then check the preview and save. The import checks the schema and will say if a field is not accepted.
+
+## Releases
+
+Because direct pushes to `main` are blocked, a release is:
+
+1. Open a pull request that bumps the version and changelog (`chore(release): X.Y.Z`).
+2. Merge it when `ci-success` is green.
+3. Tag the merge commit (`git tag vX.Y.Z && git push origin vX.Y.Z`). Pushing a tag is not blocked.
+
+Nothing is published until the owner confirms a release.
+
+## Habits we skip on purpose
+
+- No direct commits to `main`, and no force-pushes anywhere.
+- No squash merges into `dev`, because they hide which pull request a change came from.
+- No hand-merging of generated files. `docs/tools-generated.md` is regenerated with `python scripts/generate_tool_docs.py`.
+- No new tool, module or screen without a test that fails without it.
+- No claim in the docs that has not been checked. Unchecked things are marked UNVERIFIED.
+- No second pull request for the same change.