docs: establish GitHub Flow with branch protection by emredursun · Pull Request #10 · devran-ai/kit

emredursun · 2026-03-27T17:28:41Z

Summary

Document GitHub Flow (feature → PR → main) in contributing.md
Add branch naming conventions and maintainer/contributor workflows
Branch protection enabled on main: PRs required, no direct push, no force-push, no deletion

Cleanup Done (before this PR)

✂️ Deleted 3 stale feature branches (feat/v4-rebrand-optimize, feat/gitignore-by-default, fix/gitignore-untrack-hint) — all content was already in main
🔄 Reset dev branch to match main exactly (dev had no unique value)
🔒 Created GitHub ruleset main-protection enforcing PR-based workflow

Branch State (after cleanup)

Branch	Status
`main`	✅ Protected — PRs required
`dev`	✅ Synced to main
`chore/git-workflow-cleanup`	This PR

Test plan

All 3 stale branches deleted (local + remote)
dev branch reset to main (0 diff)
Branch protection ruleset active on GitHub
This PR follows the new workflow (feature branch → PR → main)

🤖 Generated with Claude Code

- Document GitHub Flow (feature branch → PR → main) in contributing.md - Add branch naming conventions (feat/, fix/, refactor/, docs/, chore/) - Add maintainer vs contributor workflow sections - Branch protection enabled on main: PRs required, no direct push, no force-push, no deletion - Deleted 3 stale feature branches and synced dev to main This formalizes the project's Git workflow from ad-hoc direct commits to a PR-based GitHub Flow — the industry standard for single-maintainer open source projects.

gemini-code-assist

Code Review

This pull request updates the contribution documentation to formalize the GitHub Flow workflow, detailing specific steps for contributors and maintainers, branch naming conventions, and branch protection rules. The review feedback suggests ensuring consistency with the root-level contributing file and adding explicit branch synchronization steps to the workflow to minimize merge conflicts.

gemini-code-assist · 2026-03-27T17:39:09Z

docs/contributing.md

 ---

-## Development Workflow
+## Git Workflow (GitHub Flow)


This document introduces the new GitHub Flow, which is a great simplification. However, there appears to be a conflicting CONTRIBUTING.md file in the root of the repository that still describes the old GitFlow process (using dev and main branches). To avoid confusion for contributors, it's crucial that the contribution guidelines are consistent. Please consider updating or removing the root CONTRIBUTING.md to reflect this new workflow.

gemini-code-assist · 2026-03-27T17:39:09Z

docs/contributing.md

 1. **Fork** the repository
-2. **Create** a feature branch
-3. **Make** your changes
-4. **Run** verification: `/verify`
-5. **Submit** a pull request
+2. **Create** a feature branch from `main`: `git checkout -b feat/my-feature`
+3. **Make** your changes (small, focused commits)
+4. **Run** verification: `npm test` and `/verify`
+5. **Push** and open a PR against `main`


The contributor workflow is missing a crucial step: syncing the forked repository with the upstream repository before creating a new branch. This is important to avoid merge conflicts and to base changes on the latest version of the code. I'd suggest adding a note about this.

Suggested change

1. **Fork** the repository

2. **Create** a feature branch

3. **Make** your changes

4. **Run** verification: `/verify`

5. **Submit** a pull request

2. **Create** a feature branch from `main`: `git checkout -b feat/my-feature`

3. **Make** your changes (small, focused commits)

4. **Run** verification: `npm test` and `/verify`

5. **Push** and open a PR against `main`

1. **Fork** the repository

2. **Sync your fork's `main` branch** with the upstream `devran-ai/kit` repository.

3. **Create** a feature branch from `main`: `git checkout -b feat/my-feature`

4. **Make** your changes (small, focused commits)

5. **Run** verification: `npm test` and `/verify`

6. **Push** and open a PR against `main`

gemini-code-assist · 2026-03-27T17:39:09Z

docs/contributing.md

+1. **Create** a branch from `main`: `git checkout -b feat/my-feature`
+2. **Develop** with conventional commits
+3. **Push** the branch: `git push -u origin feat/my-feature`
+4. **Open PR** against `main` — CI runs automatically
+5. **Merge** via GitHub (squash or merge commit)
+6. **Delete** the feature branch after merge


To ensure feature branches are always created from the latest version of main, it's a good practice to add an explicit step for syncing the main branch before creating a new feature branch. This helps prevent integration issues.

Suggested change

1. **Create** a branch from `main`: `git checkout -b feat/my-feature`

2. **Develop** with conventional commits

3. **Push** the branch: `git push -u origin feat/my-feature`

4. **Open PR** against `main` — CI runs automatically

5. **Merge** via GitHub (squash or merge commit)

6. **Delete** the feature branch after merge

1. **Sync `main`**: `git checkout main && git pull origin main`

2. **Create** a branch from `main`: `git checkout -b feat/my-feature`

3. **Develop** with conventional commits

4. **Push** the branch: `git push -u origin feat/my-feature`

5. **Open PR** against `main` — CI runs automatically

6. **Merge** via GitHub (squash or merge commit)

7. **Delete** the feature branch after merge

…Hub Flow Resolves all 3 gemini-code-assist review comments on PR #10: 1. HIGH: Root CONTRIBUTING.md still described GitFlow (dev → main). Rewrote to match GitHub Flow (feature → PR → main). Removed all references to dev branch as integration target, hotfix branches, and GitFlow release cycle. 2. MEDIUM: Added "Sync fork with upstream" step to contributor workflow in docs/contributing.md. 3. MEDIUM: Added explicit "Sync main" step to maintainer workflow in docs/contributing.md. Both files now describe identical GitHub Flow with consistent branch naming, protection rules, and code standards (immutable patterns, structured logging).

emredursun · 2026-03-27T21:11:16Z

/gemini review

gemini-code-assist

Code Review

This pull request transitions the project's branching strategy from GitFlow to GitHub Flow, updating documentation to reflect that all changes now target the main branch. It also introduces new code standards for immutability and structured logging while removing references to CheatSheet.md. Review feedback identifies a potential test regression caused by the removal of CheatSheet.md from the synchronization checklist and suggests streamlining the workflow instructions in both CONTRIBUTING.md and docs/contributing.md to reduce redundancy.

gemini-code-assist · 2026-03-27T21:13:22Z

CONTRIBUTING.md

 - [ ] All tests pass (`npm test`)
 - [ ] No hardcoded secrets
- [ ] Counts are synchronized (manifest, README, CheatSheet, CLI)
+- [ ] Counts are synchronized (manifest, README, CLI)


This change removes CheatSheet.md from the synchronization checklist. However, based on the repository context, there appears to be a test in tests/structural/version-sync.test.js that verifies version synchronization for CheatSheet.md. This change will likely cause that test to fail. Please update or remove the corresponding test to maintain build integrity.

gemini-code-assist · 2026-03-27T21:13:22Z

CONTRIBUTING.md

 ### Creating a Feature Branch

 ```bash
-git checkout dev
-git pull origin dev
+git checkout main
+git pull origin main
 git checkout -b feat/your-feature-name
 ```

 ## Development Workflow

-1. **Create branch** from `dev` (see above)
-2. **Make changes** and commit with conventional messages
-3. **Run tests**: `npm test`
-4. **Push** your branch: `git push -u origin feat/your-feature-name`
-5. **Create PR** targeting `dev`
-6. **Wait** for CI checks and reviewer approval
-7. **Squash-merge** into `dev`
+1. **Sync `main`**: `git checkout main && git pull origin main`
+2. **Create branch**: `git checkout -b feat/your-feature-name`
+3. **Make changes** and commit with conventional messages
+4. **Run tests**: `npm test`
+5. **Push** your branch: `git push -u origin feat/your-feature-name`
+6. **Create PR** targeting `main`
+7. **Wait** for CI checks and reviewer approval
+8. **Squash-merge** after approval


The "Creating a Feature Branch" section and the first two steps of the "Development Workflow" are redundant as they describe the same set of commands. To improve clarity and reduce duplication, I suggest removing the "Creating a Feature Branch" section and combining the first two steps of the workflow into a single, clearer first step. This also requires re-numbering the subsequent steps.

Suggested change

### Creating a Feature Branch

```bash

git checkout dev

git pull origin dev

git checkout main

git pull origin main

git checkout -b feat/your-feature-name

```

## Development Workflow

1. **Create branch** from `dev` (see above)

2. **Make changes** and commit with conventional messages

3. **Run tests**: `npm test`

4. **Push** your branch: `git push -u origin feat/your-feature-name`

5. **Create PR** targeting `dev`

6. **Wait** for CI checks and reviewer approval

7. **Squash-merge** into `dev`

1. **Sync `main`**: `git checkout main && git pull origin main`

2. **Create branch**: `git checkout -b feat/your-feature-name`

3. **Make changes** and commit with conventional messages

4. **Run tests**: `npm test`

5. **Push** your branch: `git push -u origin feat/your-feature-name`

6. **Create PR** targeting `main`

7. **Wait** for CI checks and reviewer approval

8. **Squash-merge** after approval

## Development Workflow

1. **Create a branch from `main`**:

```bash

git checkout main

git pull origin main

git checkout -b feat/your-feature-name

Make changes and commit with conventional messages

Run tests: npm test

Push your branch: git push -u origin feat/your-feature-name

Create PR targeting main

Wait for CI checks and reviewer approval

Squash-merge after approval

gemini-code-assist · 2026-03-27T21:13:22Z

docs/contributing.md

+1. **Sync `main`**: `git checkout main && git pull origin main`
+2. **Create** a branch from `main`: `git checkout -b feat/my-feature`
+3. **Develop** with conventional commits
+4. **Push** the branch: `git push -u origin feat/my-feature`
+5. **Open PR** against `main` — CI runs automatically
+6. **Merge** via GitHub (squash or merge commit)
+7. **Delete** the feature branch after merge


The first two steps in the "For Maintainers" workflow are redundant. They can be combined into a single, clearer step for creating a feature branch, which improves readability. The subsequent steps should be re-numbered accordingly.

Suggested change

1. **Sync `main`**: `git checkout main && git pull origin main`

2. **Create** a branch from `main`: `git checkout -b feat/my-feature`

3. **Develop** with conventional commits

4. **Push** the branch: `git push -u origin feat/my-feature`

5. **Open PR** against `main` — CI runs automatically

6. **Merge** via GitHub (squash or merge commit)

7. **Delete** the feature branch after merge

1. **Create** a branch from `main`:

```bash

git checkout main

git pull origin main

git checkout -b feat/my-feature

Develop with conventional commits

Push the branch: git push -u origin feat/my-feature

Open PR against main — CI runs automatically

Merge via GitHub (squash or merge commit)

Delete the feature branch after merge

…heatSheet ref Resolves 3 gemini-code-assist findings from review #4023726636: 1. HIGH: Restored CheatSheet.md to sync checklist in CONTRIBUTING.md. File and its version-sync test both exist — removing it from the checklist was an oversight. Test confirmed passing (8/8). 2. MEDIUM: Removed redundant "Creating a Feature Branch" section from CONTRIBUTING.md. Merged git checkout/pull/branch commands into Development Workflow step 1 as a single code block. 3. MEDIUM: Consolidated maintainer workflow in docs/contributing.md. Merged "Sync main" and "Create branch" into a single step with inline code block. Re-numbered subsequent steps.

emredursun · 2026-03-27T21:24:45Z

/gemini review

gemini-code-assist

Code Review

This pull request transitions the project's branching strategy from GitFlow to GitHub Flow, simplifying the development and release processes by targeting the main branch directly. It also introduces new code standards for immutable patterns and structured logging. Review feedback identifies a sequential numbering error in the development workflow, suggests restoring lost details regarding PR templates and specific reviewers, and recommends consolidating duplicate branch naming guidelines found in both the root and documentation folders to ensure a single source of truth.

I am having trouble creating individual review comments. Click here to see my feedback.

CONTRIBUTING.md (57-61)

The numbering in the development workflow list is incorrect. It jumps from step 2 to 4, and all subsequent steps are off by one. This can be confusing for contributors. Please correct the numbering to be sequential.

3. **Run tests**: `npm test`
4. **Push** your branch: `git push -u origin feat/your-feature-name`
5. **Create PR** targeting `main`
6. **Wait** for CI checks and reviewer approval
7. **Squash-merge** after approval

CONTRIBUTING.md (166-173)

The "Pull Request Process" section has been removed. While the new "Development Workflow" covers most of the steps, some valuable information like "Fill in the PR template completely" and the mention of reviewers ("gemini-code-assist + human") has been lost. This information is helpful for contributors to submit complete and well-formed pull requests. Consider re-integrating these details into the "Development Workflow" section.

docs/contributing.md (40-48)

This file introduces a "Branch Naming" table that is very similar to the "Branch Rules" table in the root CONTRIBUTING.md file. However, the format and examples are slightly different. Having two sources of truth for contribution guidelines can be confusing. To ensure consistency, consider making one file the single source of truth and linking to it from the other, or ensuring the content is identical.

…round 2 Telegram guard fix: - Guard was pushing ONLY to per-chat scope, then returning early. Plugin would then overwrite all_private_chats with its defaults. - Now pushes to all_private_chats FIRST (counters plugin overwrite), then per-chat for additional specificity. Both scopes covered. - Private chat menus now persist across session restarts. Gemini review fixes (3 findings from review #4023726636): - HIGH: Restored CheatSheet.md to sync checklist (file + test exist) - MEDIUM: Removed redundant "Creating a Feature Branch" in CONTRIBUTING.md - MEDIUM: Consolidated maintainer workflow steps in docs/contributing.md

Race condition fix: Plugin may call setMyCommands AFTER the guard's initial 8s push, overwriting the menu with 3 default commands. Changes: - Extract pushCommands() helper for reuse across initial push and retry - Add healthCheck() that runs 15s after initial push: 1. Queries Telegram API for current all_private_chats commands 2. Compares count against cache 3. If drift detected (plugin overwrote), re-pushes automatically - Health check is fire-and-forget (non-blocking for SessionStart hook) Timeline: session start → 8s initial push → 15s health check → done If plugin overwrites between 8s-23s, health check catches and fixes it.

Root cause: Telegram scope hierarchy is chat > all_private_chats > default. Guard was pushing stale 4-command cache to per-chat scope, which overrode the correct 22-command all_private_chats scope. Users saw only 4 commands. Fix: Guard now pushes ONLY to all_private_chats scope. Per-chat scope is never set, so all_private_chats (with full 22 commands) takes effect.

- Remove orphan JSDoc block (leftover from pre-refactor runGuard) - Remove dead readAllowedUsers() + accessPath (per-chat scope removed) - Update module header: document all_private_chats strategy + health check No behavioral changes — dead code removal only.

CRITICAL: Health check was non-functional — process.exit() killed the process before the 15s health check timer fired. runGuard() now returns { code, healthCheckDone } so the caller can await the health check promise before exiting. Verified: health check now runs and logs. MEDIUM: Fixed CONTRIBUTING.md step numbering (1,2,4,5,6,7,8 → 1-7). MEDIUM: Fixed unused normBase variable in patchPlugin() — was declared but line 288 used resolvedBase.replace() directly instead. Now uses normBase consistently.

gemini-code-assist bot reviewed Mar 27, 2026

View reviewed changes

emredursun added 5 commits March 27, 2026 22:27

emredursun merged commit 4851b27 into main Mar 27, 2026
4 checks passed

emredursun deleted the chore/git-workflow-cleanup branch March 27, 2026 23:00

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: establish GitHub Flow with branch protection#10

docs: establish GitHub Flow with branch protection#10
emredursun merged 8 commits intomainfrom
chore/git-workflow-cleanup

emredursun commented Mar 27, 2026

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot Mar 27, 2026

Uh oh!

gemini-code-assist bot Mar 27, 2026

Uh oh!

gemini-code-assist bot Mar 27, 2026

Uh oh!

emredursun commented Mar 27, 2026

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot Mar 27, 2026

Uh oh!

gemini-code-assist bot Mar 27, 2026

Uh oh!

gemini-code-assist bot Mar 27, 2026

Uh oh!

emredursun commented Mar 27, 2026

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

emredursun commented Mar 27, 2026

Summary

Cleanup Done (before this PR)

Branch State (after cleanup)

Test plan

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

emredursun commented Mar 27, 2026

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

emredursun commented Mar 27, 2026

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

CONTRIBUTING.md (57-61)

CONTRIBUTING.md (166-173)

docs/contributing.md (40-48)

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant