@logickernel/agileflow 0.16.1 → 0.17.1

package/docs/conventional-commits.md

@@ -1,252 +0,0 @@
-# Conventional Commits
-
-AgileFlow uses [Conventional Commits](https://www.conventionalcommits.org/) to automatically determine version bumps and generate release notes.
-
-## What are Conventional Commits?
-
-The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history, which makes it easier to write automated tools on top of. This convention dovetails with [SemVer](https://semver.org/), by describing the features, fixes, and breaking changes made in commit messages.
-
-The commit message should be structured as follows:
-
-```
-<type>[optional scope]: <description>
-
-[optional body]
-
-[optional footer(s)]
-```
-
-The commit contains the following structural elements, to communicate intent to the consumers of your library:
-
-- **`fix:`** — A commit of the type `fix` patches a bug in your codebase (this correlates with **PATCH** in Semantic Versioning).
-- **`feat:`** — A commit of the type `feat` introduces a new feature to the codebase (this correlates with **MINOR** in Semantic Versioning).
-- **`BREAKING CHANGE:`** — A commit that has a footer `BREAKING CHANGE:`, or appends a `!` after the type/scope, introduces a breaking API change (correlating with **MAJOR** in Semantic Versioning). A `BREAKING CHANGE` can be part of commits of any type.
-- **Other types** — Types other than `fix:` and `feat:` are allowed (e.g., `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, and others). These have no implicit effect in Semantic Versioning (unless they include a `BREAKING CHANGE`).
-- **Scope** — A scope may be provided to a commit's type, to provide additional contextual information and is contained within parenthesis, e.g., `feat(parser): add ability to parse arrays`.
-- **Footers** — Footers other than `BREAKING CHANGE: <description>` may be provided and follow a convention similar to git trailer format.
-
----
-
-## How to Choose a Commit Type
-
-Use this decision flow to choose the right commit type:
-
-```mermaid
-flowchart TD
-  Start([Start]) --> A{Does it add functionality?}
-
-  A -- "yes" --> F[feat:]
-  A -- "no" --> B{Does it fix functionality?}
-
-  B -- "yes" --> X[fix:]
-  B -- "no" --> C{Is it worth an entry in the changelog?}
-
-  C -- "yes" --> W[Choose best: docs, ci, style, etc.]
-  C -- "no" --> D[chore:]
-
-  W --> E{Is it a breaking change?}
-  F --> E
-  X --> E
-  D --> E
-
-  E -- "no" --> Z([Commit])
-  E -- "yes" --> G[Add ! to type/scope or BREAKING CHANGE: in body]
-  G --> Z
-```
-
-### Quick Decision Guide
-
-1. **Adds new functionality?** → `feat:`
-2. **Fixes broken functionality?** → `fix:`
-3. **Work in progress?** → `wip:` (not included in releases)
-4. **Otherwise?** → Choose the most appropriate:
-   - `docs:` — Documentation changes
-   - `ci:` — CI/CD changes
-   - `style:` — Code style (formatting, whitespace)
-   - `chore:` — Maintenance tasks
-   - `test:` — Test changes
-   - `refactor:` — Code refactoring
-   - `perf:` — Performance improvements
-   - `build:` — Build system changes
-   - `revert:` — Revert previous commits
-5. **Breaking change?** → Add `!` after type/scope or include `BREAKING CHANGE:` in body
-
-### Examples
-
-```bash
-# Adds functionality
-feat: add user authentication
-feat(auth): add OAuth2 support
-
-# Fixes functionality
-fix: resolve login validation error
-fix(api): handle timeout errors
-
-# Work in progress
-wip: implement user authentication
-
-# Other types
-docs: update API reference
-ci: update GitHub Actions workflow
-style: format code with prettier
-chore: update dependencies
-
-# Breaking changes
-feat!: remove deprecated API endpoints
-feat: change response format
-
-BREAKING CHANGE: Response now uses camelCase
-```
-
----
-
-## Commit Types and Version Impact
-
-| Type | Description | 0.x.x | 1.0.0+ |
-|------|-------------|--------|-------|
-| BREAKING CHANGE | Changes that break backward compatibility <br> (e.g., removed APIs, changed function signatures, modified response formats) | Minor | Major |
-| `feat` | New features | Minor | Minor |
-| `fix` | Bug fixes | Patch | Patch |
-|  | Any other type of commit | None | None |
-
-When multiple commits exist, the highest priority wins.
-
-### Breaking Changes
-
-Breaking changes trigger a major version bump (or minor for 0.x.x):
-
-```bash
-# Using ! suffix
-feat!: remove deprecated API
-
-# Using footer
-feat: change response format
-
-BREAKING CHANGE: Response now uses camelCase
-```
-
----
-
-## Release Notes Generation
-
-AgileFlow groups commits by type for release notes:
-
-```
-v1.2.4
-
-### Features
-- add user dashboard
-- implement API rate limiting
-
-### Bug fixes
-- resolve login validation error
-- fix timeout on large uploads
-
-### Performance improvements
-- optimize database queries
-
-### Documentation
-- update API reference
-```
-
-Chore commits are omitted from release notes unless they include a breaking change.
-
-### Breaking Changes in Notes
-
-Breaking changes are highlighted:
-
-```
-v2.0.0
-
-### Features
-- BREAKING: remove deprecated API endpoints
-- BREAKING: change authentication flow
-```
-
-
----
-
-## Non-Conventional Commits
-
-Commits not following the format:
-- Trigger **no bump** by default
-- Appear under "Other changes" in release notes
-
----
-
-## Best Practices
-
-1. Use Clear Types
-
-```bash
-# ✅ Correct type
-feat: add login feature
-fix: resolve crash on startup
-
-# ❌ Wrong type
-fix: add login feature  # Should be feat
-feat: fix crash         # Should be fix
-```
-
-
-2. Write Clear Descriptions
-
-```bash
-# ✅ Clear and specific
-feat: add two-factor authentication via SMS
-fix: prevent timeout on uploads larger than 100MB
-
-# ❌ Vague
-feat: add 2fa
-fix: fix timeout
-```
-
-3. Mark Breaking Changes
-
-```bash
-# ✅ Properly marked
-feat!: remove deprecated endpoints
-
-# ❌ Breaking change not marked
-feat: remove deprecated endpoints
-```
-
-4. Use Present Tense
-
-```bash
-# ✅ Present tense
-feat: add user authentication
-
-# ❌ Past tense
-feat: added user authentication
-```
-
-5. Use Chore for *work in progress*
-
-```bash
-# ✅ Use chore so an entry is not added to the changelog
-chore: add framework for form validation
-
-# ❌ Used something else that will add a meaningless entry to the changelog
-refactor: add framework for form validation
-```
-
-6. Add Meaningful Scopes when applicable
-
-```bash
-# ✅ Helpful scope
-feat(auth): add OAuth2 support
-fix(api): handle timeout errors
-
-# ✅ Also fine without scope
-feat: add OAuth2 support
-fix: handle timeout errors
-```
-
----
-
-## Related Documentation
-
-- [Getting Started](./getting-started.md) — Quick start
-- [Release Management](./release-management.md) — Version management
-- [Branching Strategy](./branching-strategy.md) — Git workflow

package/docs/getting-started.md

@@ -1,231 +0,0 @@
-# Getting Started
-
-Get up and running with AgileFlow in minutes. This guide covers local usage and CI/CD integration.
-
-## What You'll Learn
-
-- How to preview your next version locally
-- How to set up automatic versioning in CI/CD
-- How conventional commits affect version bumps
-
-## Prerequisites
-
-- Node.js 14+ (for local usage)
-- A Git repository with commit history
-- Basic understanding of conventional commits
-
----
-
-## Quick Start
-
-### 1. Preview Your Next Version
-
-Run AgileFlow in any Git repository:
-
-```bash
-npx @logickernel/agileflow
-```
-
-Example output:
-```
-Current version: v1.2.3
-Next version: v1.2.4
-
-Changelog:
-### fix
-- resolve authentication issue
-- correct null handling in user lookup
-
-### docs
-- update README with usage examples
-```
-
-### 2. Get Just the Version
-
-Use `--quiet` to output only the version (useful for scripts):
-
-```bash
-VERSION=$(npx @logickernel/agileflow --quiet)
-echo "Next version: $VERSION"
-```
-
----
-
-## CI/CD Integration
-
-AgileFlow uses a **decoupled architecture**:
-
-1. **AgileFlow creates a version tag** (on merge to main)
-2. **Your pipelines trigger on the tag** (build, deploy, etc.)
-
-```
-Merge to main ──▶ AgileFlow ──▶ Tag v1.2.3 ──▶ Your build/deploy
-```
-
-### GitHub Actions
-
-**Step 1**: Add a secret `AGILEFLOW_TOKEN` with a Personal Access Token (`contents: write` permission).
-
-**Step 2**: Create `.github/workflows/version.yml`:
-
-```yaml
-name: Version
-on:
-  push:
-    branches: [main]
-
-jobs:
-  version:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-
-      - name: Create version tag
-        env:
-          AGILEFLOW_TOKEN: ${{ secrets.AGILEFLOW_TOKEN }}
-        run: npx @logickernel/agileflow github
-```
-
-**Step 3**: Create `.github/workflows/release.yml` for builds:
-
-```yaml
-name: Release
-on:
-  push:
-    tags:
-      - 'v*'
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - run: |
-          VERSION=${GITHUB_REF#refs/tags/}
-          echo "Building $VERSION"
-          docker build -t myapp:$VERSION .
-```
-
-### GitLab CI
-
-**Step 1**: Add a CI/CD variable `AGILEFLOW_TOKEN` with a Project Access Token (`api` scope, `Maintainer` role).
-
-**Step 2**: Update `.gitlab-ci.yml`:
-
-```yaml
-# Runs on merge to main - creates the tag
-agileflow:
-  image: node:20
-  script:
-    - npm install -g @logickernel/agileflow
-    - npx @logickernel/agileflow gitlab
-  rules:
-    - if: '$CI_COMMIT_BRANCH == "main"'
-
-# Runs on tag creation - builds the release
-build:
-  stage: build
-  script:
-    - echo "Building $CI_COMMIT_TAG"
-    - docker build -t myapp:$CI_COMMIT_TAG .
-  rules:
-    - if: '$CI_COMMIT_TAG =~ /^v/'
-```
-
-### Native Git Push
-
-For other platforms:
-
-```bash
-npx @logickernel/agileflow push
-```
-
-This creates an annotated tag and pushes it. Configure your CI to trigger on tags.
-
----
-
-## How Version Bumps Work
-
-AgileFlow analyzes commit messages to determine the bump:
-
-| Commit Type | Example | 0.x.x | 1.0.0+ |
-|-------------|---------|-------|--------|
-| Breaking change | `feat!: redesign API` | **Minor** (0.1.0 → 0.2.0) | **Major** (1.0.0 → 2.0.0) |
-| Feature | `feat: add login` | **Minor** | **Minor** |
-| Fix | `fix: resolve crash` | **Patch** | **Patch** |
-| Everything else | `docs: update README` | No bump | No bump |
-
-### No Bump Needed
-
-If all commits are docs/chore/style types, AgileFlow skips tag creation.
-
----
-
-## Your First Release
-
-### Starting Fresh
-
-No version tags? AgileFlow starts from v0.0.0:
-
-```bash
-git commit -m "feat: initial project setup"
-# → Creates v0.0.1
-```
-
-### Creating v1.0.0
-
-Version 1.0.0 is your first stable release. Create it manually when ready:
-
-```bash
-git tag -a v1.0.0 -m "First stable release"
-git push origin v1.0.0
-```
-
-After v1.0.0, AgileFlow continues with standard semantic versioning.
-
----
-
-## Common Questions
-
-**How does the decoupled approach work?**
-
-AgileFlow only creates version tags. Your build/deploy pipelines are separate workflows that trigger on tag creation. This keeps versioning independent from your build process.
-
-**What if no version bump is needed?**
-
-AgileFlow skips tag creation. No tag means no build/deploy triggered.
-
-**Can I preview without creating tags?**
-
-Yes! Running `npx @logickernel/agileflow` without a command shows the next version without creating anything.
-
----
-
-## Troubleshooting
-
-### "AGILEFLOW_TOKEN not set" Error
-- Verify the environment variable is configured
-- Check token permissions (GitHub: `contents: write`, GitLab: `api` scope)
-
-### Tag Created but Build Didn't Run
-- Ensure your release workflow triggers on `tags: ['v*']`
-- Check the tag pattern in your CI configuration
-
-### No Version Bump Detected
-- Use conventional commit format (`type: description`)
-- Include bump-triggering types: `feat` (minor) or `fix` (patch)
-
----
-
-## Next Steps
-
-- [CLI Reference](./cli-reference.md) — All commands and options
-- [Installation Guide](./installation.md) — Detailed setup
-- [Conventional Commits](./conventional-commits.md) — Commit format
-- [Version-Centric CI/CD](./version-centric-cicd.md) — The methodology