Skip to content

AGENT.md

Latest commit

 

History

History
172 lines (130 loc) · 4.15 KB

AGENT.md

File metadata and controls

172 lines (130 loc) · 4.15 KB
Raw

Sinau LMS - Agent Workflow Guide

This file defines the development workflow, branching strategy, and release process for Sinau LMS. All agents working on this project must follow these rules.

Branching Strategy

main (production)
  |
  └── develop (integration)
        |
        └── feature/* (per-feature branches)

Branches

Branch Purpose Protected
main Production releases. Only tagged versions. Yes - no direct push
develop Integration branch. All features merge here. Yes - PR + checks required
feature/* Individual feature development. Created from develop. No

Feature Development Workflow

1. Create feature branch from develop
   $ git checkout develop
   $ git pull origin develop
   $ git checkout -b feature/course-clone

2. Implement changes
   - Write code
   - Write/update tests
   - Update docs if needed

3. Commit (conventional commits)
   $ git commit -m "feat(courses): add course clone endpoint"

4. Push and create PR to develop
   $ git push origin feature/course-clone
   $ gh pr create --base develop --title "feat(courses): add course clone endpoint"

5. CI must pass (tests, lint, build)
   CTO agent merges when CI is green.

6. After merge, delete feature branch
   $ git branch -d feature/course-clone
   $ git push origin --delete feature/course-clone

Commit Convention

Follow Conventional Commits:

feat(scope): description
fix(scope): description
docs(scope): description
refactor(scope): description
chore(scope): description
test(scope): description
ci(scope): description

Examples:

  • feat(courses): add course clone endpoint
  • fix(auth): resolve JWT expiry race condition
  • docs(prd): update F-010 search spec
  • refactor(media): extract StorageBackend trait

Release Workflow

Step 1: Verify readiness
  - All planned features for this version are merged to develop
  - CHANGELOG.md is updated with all changes
  - Documentation is complete (VitePress docs site)
  - All tests pass

Step 2: PR develop -> main
  $ git checkout develop
  $ git pull origin develop
  $ git checkout main
  $ git pull origin main
  $ gh pr create --base main --head develop --title "Release v0.x.0"

Step 3: Review and merge
  - CTO reviews the PR
  - Verify CHANGELOG.md completeness
  - Verify docs are up-to-date
  - Merge PR (main <- develop)

Step 4: Tag and push
  $ git checkout main
  $ git pull origin main
  $ git tag v0.x.0
  $ git push origin main --tags
  # This triggers release CI (Docker build, publish, deploy)

Step 5: Post-release
  - Verify deployment
  - Announce release (changelog summary)
  - Update develop to sync with main
  $ git checkout develop
  $ git merge main
  $ git push origin develop

Release Checklist

Before creating the release PR:

  • CHANGELOG.md updated with version header and all changes
  • VitePress docs site updated (if applicable)
  • README.md reflects current state
  • .env.example is up-to-date
  • All Tier 1 features for this version are implemented
  • Tests pass on CI
  • No known critical bugs

CI/CD Pipeline

On PR to develop

  1. Rust: cargo test + cargo clippy
  2. Rust: cargo build --release (compile check)
  3. Frontend: bun run check (type check)
  4. Frontend: bun run build (build check)
  5. Cora code review (non-blocking advisory)

On tag push (release)

  1. Build Docker images (server + web)
  2. Push to container registry (Zot)
  3. Deploy to staging/production (Traefik)

Versioning

Follow semantic versioning, but stay in 0.x.x indefinitely:

  • Patch (0.0.x): Bug fixes, documentation updates
  • Minor (0.x.0): New features, feature batches
  • NEVER jump to 1.0.0 until the project is stable and mature

Git Configuration

All commits must use:

user.name=ajianaz
user.email=ajianaz@users.noreply.github.com

DO NOT

  • Push directly to main or develop (always PR)
  • Force push to any branch
  • Include hardcoded secrets or credentials
  • Merge without CI passing (except docs-only PRs)
  • Skip CHANGELOG.md updates on releases
  • Create tags from non-main branch