@logickernel/agileflow 0.4.0 → 0.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (15) hide show
  1. package/README.md +133 -211
  2. package/docs/README.md +39 -24
  3. package/docs/best-practices.md +201 -234
  4. package/docs/branching-strategy.md +153 -254
  5. package/docs/cli-reference.md +84 -64
  6. package/docs/configuration.md +154 -167
  7. package/docs/conventional-commits.md +207 -160
  8. package/docs/getting-started.md +162 -117
  9. package/docs/installation.md +244 -106
  10. package/docs/migration-guide.md +212 -299
  11. package/docs/release-management.md +195 -384
  12. package/docs/troubleshooting.md +276 -250
  13. package/docs/version-centric-cicd.md +239 -116
  14. package/package.json +3 -2
  15. package/src/utils.js +23 -6
package/README.md CHANGED
@@ -2,288 +2,210 @@
2
2
 
3
3
  # AgileFlow
4
4
 
5
- In today's fast-paced software development landscape, maintaining clarity, consistency, and efficiency in the release process is essential. AgileFlow is a streamlined yet powerful versioning system, branching strategy, and CI/CD tool designed for software teams of all sizes and projects of any scale.
5
+ In today's fast-paced software development landscape, maintaining clarity, consistency, and efficiency in the release process is essential. AgileFlow is a streamlined yet powerful versioning system designed for software teams of all sizes and projects of any scale.
6
6
 
7
- AgileFlow enforces Semantic Versioning and integrates a robust branching strategy for development and deployment. It seamlessly works with GitLab CI pipelines to ensure a structured, efficient, and predictable development lifecycle. **All versions are calculated from the main branch's commit history**, ensuring consistent versioning and release notes. Whether for small projects or large-scale deployments, AgileFlow is an indispensable tool that simplifies versioning and release management.
7
+ AgileFlow enforces Semantic Versioning and integrates seamlessly with your CI/CD pipeline to ensure a structured, efficient, and predictable development lifecycle. **All versions are calculated from the main branch's commit history** using [Conventional Commits](https://www.conventionalcommits.org/), ensuring consistent versioning and release notes. Whether for small projects or large-scale deployments, AgileFlow simplifies versioning and release management.
8
8
 
9
9
  ![AgileFlow workflow example diagram](./media/diagram.jpg)
10
10
 
11
- AgileFlow works integrated with the CI/CD engine to **automatically create a new version** every time there's a merge into the main branch, incrementing the patch number based on the latest identifiable version in the repository.
11
+ AgileFlow works with your CI/CD engine to **automatically create a new version tag** every time there's a merge into the main branch. Your existing build and deploy pipelines then trigger on tag creation, creating a clean separation between versioning and release processes. This decoupled architecture means AgileFlow focuses solely on versioning, while your build and deploy workflows remain independent.
12
12
 
13
- # Installation
13
+ ---
14
14
 
15
- ## GitLab CI
15
+ ## Quick Start
16
16
 
17
- AgileFlow integrates with GitLab CI to automate version tagging. Add the following line at the top of `.gitlab-ci.yml`:
17
+ ### Preview Your Next Version
18
18
 
19
- ```yml
20
- include:
21
- - remote: https://code.logickernel.com/kernel/agileflow/-/raw/main/templates/AgileFlow.gitlab-ci.yml
19
+ ```bash
20
+ npx @logickernel/agileflow
22
21
  ```
23
22
 
24
- Introducing a simple workflow in which an environment variable $VERSION is available.
25
-
26
- **Learn More**: [Complete Installation Guide](./docs/installation.md) - Step-by-step setup for different platforms
27
-
28
- > [!NOTE]
29
- > AgileFlow uses the GitLab API to create version tags remotely, eliminating the need for repository write permissions. You'll need to configure the `AGILEFLOW_TOKEN` environment variable with API access. See the [Installation Guide](./docs/installation.md) for complete setup instructions.
23
+ ### Create a Version Tag
30
24
 
31
25
 
32
- # Core Principles
26
+ **Push to Remote Git Repository:**
27
+ ```bash
28
+ npx @logickernel/agileflow push
29
+ ```
33
30
 
34
- ## Main Branch Strategy
31
+ #### CD/CI
35
32
 
36
- The main branch is the core of the AgileFlow framework. It serves as the single source of truth for all releases and versioning.
33
+ **GitHub Actions:**
34
+ ```bash
35
+ npx @logickernel/agileflow github
36
+ ```
37
37
 
38
- **Key Benefits:**
39
- - **Single Version Sequence**: All versions (v1.0.0, v1.0.1, v1.1.0, etc.) are created from the same branch
40
- - **Simplified Workflow**: No need to manage multiple release branches
41
- - **Consistent History**: All releases share the same commit history and lineage
42
- - **Easy Rollbacks**: Simple to revert to any previous version since all versions are on the same branch
38
+ **GitLab CI:**
39
+ ```bash
40
+ npx @logickernel/agileflow gitlab
41
+ ```
43
42
 
44
- **Version Management:**
45
- - Patch versions (v1.0.0 → v1.0.1) are automatically incremented on each merge to main
46
- - Minor versions (v1.0.0 → v1.1.0) are created by merging significant features
47
- - Major versions (v1.0.0 → v2.0.0) are created for breaking changes
43
+ **Learn More**: [Getting Started Guide](./docs/getting-started.md) • [CLI Reference](./docs/cli-reference.md)
48
44
 
49
- **Learn More**: [Branching Strategy Guide](./docs/branching-strategy.md) - Complete guide to AgileFlow's branching approach
45
+ ---
50
46
 
51
- ## Development Branches
47
+ ## CI/CD Integration
52
48
 
53
- Development branches are used for feature additions and bug fixes. They branch off the main branch and merge back into it when ready. Consider using expressive names depending on their purpose, e.g.: `dev/*`, `feat/*`, `fix/*`, and `hotfix/*`.
49
+ AgileFlow uses a **two-step decoupled approach**:
54
50
 
55
- After the contribution is ready, the development branch is merged into main, preferably using a [Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) a [Merge Request](https://docs.gitlab.com/ee/user/project/merge_requests/) or similar.
51
+ ### Step 1: Version Creation (AgileFlow)
56
52
 
57
- **Learn More**: [Getting Started Guide](./docs/getting-started.md) - Quick start for new AgileFlow users
53
+ Create a workflow that runs AgileFlow when code is merged to main:
58
54
 
59
- # Version-Centric CI/CD Approach
55
+ **GitHub Actions** (`.github/workflows/version.yml`):
56
+ ```yaml
57
+ name: Version
58
+ on:
59
+ push:
60
+ branches: [main]
61
+
62
+ jobs:
63
+ version:
64
+ runs-on: ubuntu-latest
65
+ steps:
66
+ - uses: actions/checkout@v4
67
+ with:
68
+ fetch-depth: 0
69
+
70
+ - uses: actions/setup-node@v4
71
+ with:
72
+ node-version: '20'
73
+
74
+ - name: Create version tag
75
+ env:
76
+ AGILEFLOW_TOKEN: ${{ secrets.AGILEFLOW_TOKEN }}
77
+ run: npx @logickernel/agileflow github
78
+ ```
60
79
 
61
- AgileFlow introduces a revolutionary approach to CI/CD that prioritizes **version management over environment-based deployments**. This paradigm shift eliminates the complexity of managing multiple deployment branches and environments, replacing them with a streamlined, version-focused workflow.
80
+ **GitLab CI** (`.gitlab-ci.yml`):
81
+ ```yaml
82
+ agileflow:
83
+ stage: version
84
+ image: node:20-alpine
85
+ script:
86
+ - npx @logickernel/agileflow gitlab
87
+ rules:
88
+ - if: '$CI_COMMIT_BRANCH == "main"'
89
+ ```
62
90
 
63
- ## What Makes AgileFlow Different?
91
+ ### Step 2: Build & Deploy (Your Pipelines)
64
92
 
65
- - **Version-Centric**: Every deployment, test, and operation is performed on well-identified versions
66
- - **Simplified Pipeline**: Just 6 focused stages (version, test, build, deploy, e2e, clean)
67
- - **Eliminates Environment Drift**: All environments run identical versions
68
- - **Predictable Deployments**: Every deployment uses a well-identified, immutable version
69
- - **Simple Rollbacks**: Rollback to any previous version with confidence
93
+ Configure your existing build and deploy pipelines to trigger on tag creation. When AgileFlow creates a version tag (e.g., `v1.2.3`), your CI/CD platform triggers your release workflow. Use the tag name as the version identifier for your builds and deployments.
70
94
 
71
- ## Pipeline Stages
95
+ **Learn More**: [Installation Guide](./docs/installation.md) for detailed setup instructions and examples.
72
96
 
73
- Your pipeline consists of 6 focused stages that work together seamlessly:
97
+ ### Benefits of Decoupled Architecture
74
98
 
75
- 1. **Version** - AgileFlow generates semantic versions automatically
76
- 2. **Test** - Run tests against the source code before building
77
- 3. **Build** - Create versioned artifacts using the generated version
78
- 4. **Deploy** - Deploy the same version everywhere (staging, production, etc.)
79
- 5. **E2E** - Run end-to-end tests against the deployed version
80
- 6. **Clean** - Cleanup temporary resources and artifacts
99
+ - **Separation of concerns** — Versioning is independent from build/deploy
100
+ - **Flexibility** — Hook any process to tag creation
101
+ - **Reusability** — Same build pipeline works for any version
102
+ - **Simplicity** — Each pipeline has a single responsibility
81
103
 
82
- **Learn More**: [Version-Centric CI/CD Deep Dive](./docs/version-centric-cicd.md) - Comprehensive guide to AgileFlow's revolutionary CI/CD paradigm
104
+ **Learn More**: [Installation Guide](./docs/installation.md) • [Configuration](./docs/configuration.md)
83
105
 
84
- # Conventional Commits
106
+ ---
85
107
 
86
- Conventional Commits encode the intent of a change in the commit subject so that humans (and tools) can generate clear release notes and version bumps.
108
+ ## Conventional Commits
87
109
 
88
- ## Commit Format
110
+ AgileFlow uses [Conventional Commits](https://www.conventionalcommits.org/) to automatically determine version bumps and generate release notes. Commit messages follow a structured format that encodes the intent of each change:
89
111
 
90
112
  ```text
91
- type[!]?(scope)?: description
92
-
93
- [optional body]
94
-
95
- [optional footer(s)]
96
- ```
97
-
98
- ## Key Commit Types
99
-
100
- - **feat** - New features (minor version bump)
101
- - **fix** - Bug fixes (patch version bump)
102
- - **perf** - Performance improvements (patch version bump)
103
- - **refactor** - Code refactoring (patch version bump)
104
- - **build** - Build system changes (patch version bump)
105
- - **ci** - CI/CD changes (patch version bump)
106
- - **revert** - Revert previous commits (patch version bump)
107
- - **docs** - Documentation updates (no version bump)
108
- - **test** - Test additions/changes (patch version bump)
109
- - **style** - Code style changes (no version bump)
110
- - **chore** - Maintenance tasks (no version bump)
111
- - **!** - Breaking changes (major version bump)
112
-
113
- ## Example Commits
113
+ type(scope): description
114
114
 
115
- ```text
116
- feat(auth): add OIDC login flow
115
+ feat(auth): add OAuth2 login flow
117
116
  fix(api): correct null handling in user lookup
118
117
  perf(cache)!: switch to Redis cluster
119
118
  docs: update README with usage examples
120
119
  ```
121
120
 
122
- **Learn More**: [Conventional Commits Guide](./docs/conventional-commits.md) - Complete guide to commit message formatting and types
123
-
124
- # Release Management
121
+ The commit type (`feat`, `fix`, `perf`, etc.) indicates what kind of change was made, while the optional scope identifies the area affected. Breaking changes are marked with `!` or a `BREAKING CHANGE:` footer.
125
122
 
126
- ## Automatic Version Generation
123
+ **Learn More**: [Conventional Commits Guide](./docs/conventional-commits.md)
127
124
 
128
- AgileFlow automatically analyzes your commit history and determines the next semantic version based on conventional commits. Each merge to main triggers a new version:
129
-
130
- - **Patch versions** (v1.0.0 → v1.0.1) for bug fixes, performance improvements, build changes, CI changes, refactors, reverts, and tests
131
- - **Minor versions** (v1.0.0 → v1.1.0) for new features
132
- - **Major versions** (v1.0.0 → v2.0.0) for breaking changes
125
+ ---
133
126
 
134
- ## Initial Versioning (0.x.x)
127
+ ## Release Management
135
128
 
136
- When you first start using AgileFlow, the system begins at **v0.0.0** and automatically increments versions based on your commits:
129
+ ### Automatic Versioning
137
130
 
138
- - **Patch versions** (v0.0.0 → v0.0.1) for features, bug fixes, and other changes
139
- - **Minor versions** (v0.0.0 → v0.1.0) for breaking changes
131
+ Each merge to main triggers automatic version generation based on commit types. See the [Version Calculation](#version-calculation) table below for details on how versions are bumped in 0.x.x vs 1.0.0+.
140
132
 
141
- This allows you to develop and iterate while AgileFlow tracks your progress automatically.
133
+ New projects start at **v0.0.0** and automatically increment based on commits. AgileFlow will keep automatically generating versions as you develop (0.0.1, 0.0.2, 0.1.0, etc.). When your product has reached maturity and you have a stable API ready for production, create version 1.0.0 manually.
142
134
 
143
- ## Version 1.0.0 - Your First Stable Release
135
+ <details>
136
+ <summary><strong>Version 1.0.0 — First Stable Release</strong></summary>
144
137
 
145
- **Version 1.0.0 is a significant milestone** that represents your first stable, production-ready release. This version should be **created manually** when your team decides the software is ready for its first stable release.
138
+ Version 1.0.0 represents your first stable API and marks the transition from initial development to a stable, production-ready release. This version **must be created manually** when your team decides the API is stable and ready for production use.
146
139
 
147
- To create version 1.0.0:
140
+ Create it when ready:
148
141
 
149
142
  ```bash
150
- # Create the tag manually
151
143
  git tag -a v1.0.0 -m "First stable release"
152
-
153
- # Push the tag to remote
154
144
  git push origin v1.0.0
155
145
  ```
156
146
 
157
- After v1.0.0 is created, AgileFlow will continue to automatically generate subsequent versions (v1.0.1, v1.1.0, v2.0.0, etc.) based on your commit history.
158
-
159
- > [!NOTE]
160
- > The transition to 1.0.0 is a deliberate decision that should be made by your team when you're ready to declare API stability and production readiness. AgileFlow will not automatically create 1.0.0 from 0.x.x versions.
161
-
162
- ## Release Notes
147
+ After 1.0.0, AgileFlow continues automatic versioning with standard semantic versioning rules: features bump minor, fixes bump patch, and breaking changes bump major.
163
148
 
164
- AgileFlow generates comprehensive release notes by grouping changes according to their intent:
149
+ </details>
165
150
 
166
- ```text
167
- v1.2.4
168
-
169
- Features:
170
- - auth: add OIDC login flow
171
-
172
- Bug fixes:
173
- - api: correct null handling in user lookup
174
-
175
- Performance improvements:
176
- - cache: optimize Redis connection pooling
151
+ **Learn More**: [Release Management Guide](./docs/release-management.md)
177
152
 
178
- Build system:
179
- - update webpack to v5
180
- - upgrade React to 18.2.0
153
+ ---
181
154
 
182
- CI:
183
- - fix pipeline configuration
155
+ ## Version Calculation
184
156
 
185
- Refactors:
186
- - simplify authentication logic
157
+ AgileFlow analyzes commits since the last version tag to determine the appropriate version bump:
187
158
 
188
- Tests:
189
- - add integration tests for auth flow
190
- - increase test coverage to 85%
159
+ | Commit Type | Example | 0.x.x | 1.0.0+ |
160
+ |-------------|---------|-------|--------|
161
+ | Breaking change | `feat!: redesign API` | **Minor** (0.1.0 → 0.2.0) | **Major** (1.0.0 → 2.0.0) |
162
+ | Feature | `feat: add login` | **Minor** | **Minor** |
163
+ | Fix | `fix: resolve crash` | **Patch** | **Patch** |
164
+ | Performance | `perf: optimize query` | **Patch** | **Patch** |
165
+ | Refactor | `refactor: simplify logic` | **Patch** | **Patch** |
166
+ | Build/CI | `build: update deps` | **Patch** | **Patch** |
167
+ | Docs only | `docs: update README` | No bump | No bump |
168
+ | Style changes | `style: update variable name` | No bump | No bump |
191
169
 
192
- Reverts:
193
- - "feat: add experimental feature"
170
+ ---
194
171
 
195
- Documentation:
196
- - update README with usage examples
197
- ```
172
+ ## Core Principles
198
173
 
199
- **Learn More**: [Release Management Guide](./docs/release-management.md) - How to manage releases and versions effectively
174
+ ### Main Branch Strategy
200
175
 
201
- # GitLab CI Integration
176
+ The main branch is the single source of truth for all releases:
202
177
 
203
- ## Template Usage
178
+ - **Single Version Sequence** — All versions created from the same branch
179
+ - **Simplified Workflow** — No release branches needed
180
+ - **Consistent History** — All releases share the same commit history
181
+ - **Easy Rollbacks** — Deploy any previous version tag
204
182
 
205
- Include the AgileFlow template in your `.gitlab-ci.yml`:
183
+ ### Version-Centric Deployments
206
184
 
207
- ```yaml
208
- include:
209
- - local: templates/AgileFlow.gitlab-ci.yml
185
+ Every environment runs the same immutable version:
210
186
 
211
- # Your custom jobs using the VERSION variable
212
- build:
213
- stage: build
214
- script:
215
- - docker build -t myapp:${VERSION} .
216
- - docker push myapp:${VERSION}
217
- needs:
218
- - agileflow
187
+ ```
188
+ Tag v1.2.3 ──▶ Build ──▶ Staging
189
+ ──▶ Production
190
+ ──▶ Any environment
219
191
  ```
220
192
 
221
- > [!NOTE]
222
- > If you prefer to use the remote template, you can use:
223
- > ```yaml
224
- > include:
225
- > - remote: https://code.logickernel.com/kernel/agileflow/-/raw/main/templates/AgileFlow.gitlab-ci.yml
226
- > ```
227
-
228
- ## Key Benefits
229
-
230
- - **Automated Versioning**: The `agileflow` job generates versions automatically
231
- - **VERSION Variable**: Available to all subsequent stages
232
- - **Consistent Deployments**: Deploy the same version everywhere
233
- - **Simplified Rollbacks**: Rollback to any previous version with confidence
234
-
235
- **Learn More**: [GitLab CI Template Reference](./docs/gitlab-ci-template.md) - Complete reference for the AgileFlow GitLab CI template
236
-
237
- # Getting Started
238
-
239
- ## Quick Setup (5 minutes)
240
-
241
- 1. **Include the template** in your `.gitlab-ci.yml`
242
- 2. **Add your first job** using the `${VERSION}` variable
243
- 3. **Commit and push** - AgileFlow automatically generates versions
244
-
245
- ## Next Steps
246
-
247
- - Add deployment jobs for staging and production
248
- - Implement testing against deployed versions
249
- - Customize for multiple services
250
- - Set up environment-specific configurations
251
-
252
- **Learn More**: [Getting Started Guide](./docs/getting-started.md) - Step-by-step setup and examples
253
-
254
- # Advanced Topics
255
-
256
- ## Migration from Traditional CI/CD
257
-
258
- If you're currently using a traditional branch-based approach:
259
-
260
- 1. **Start with AgileFlow** - Include the template and let it generate versions
261
- 2. **Gradually simplify** - Remove environment-specific branches over time
262
- 3. **Update deployments** - Modify scripts to use `${VERSION}` variable
263
- 4. **Standardize testing** - Run tests against the deployed version
264
- 5. **Document changes** - Update runbooks to reference versions
265
-
266
- ## Best Practices
267
-
268
- - Always use the `${VERSION}` variable from AgileFlow
269
- - Deploy the same version to all environments
270
- - Test against deployed versions, not source code
271
- - Use conventional commits for automatic versioning
272
- - Keep deployment scripts identical across environments
273
-
274
- **Learn More**: [Advanced Topics](./docs/README.md#advanced-topics) - Migration guides, best practices, and troubleshooting
275
-
276
- # Documentation
277
-
278
- For comprehensive guides and detailed explanations, see our [documentation folder](./docs/README.md).
279
-
280
- ## Quick Navigation
281
-
282
- - **New to AgileFlow?** Start with [Getting Started](./docs/getting-started.md)
283
- - **Want to understand the approach?** Read [Version-Centric CI/CD](./docs/version-centric-cicd.md)
284
- - **Ready to implement?** Follow [GitLab CI Template Reference](./docs/gitlab-ci-template.md)
285
- - **Need help?** Check [Troubleshooting](./docs/troubleshooting.md)
193
+ **Learn More**: [Branching Strategy](./docs/branching-strategy.md) • [Version-Centric CI/CD](./docs/version-centric-cicd.md)
286
194
 
287
195
  ---
288
196
 
289
- **Ready to transform your CI/CD?** Start with AgileFlow today and experience the benefits of a version-centric, streamlined deployment process! 🚀
197
+ ## Documentation
198
+
199
+ | Guide | Description |
200
+ |-------|-------------|
201
+ | [Getting Started](./docs/getting-started.md) | Quick start for new users |
202
+ | [Installation](./docs/installation.md) | Setup for GitHub Actions and GitLab CI |
203
+ | [CLI Reference](./docs/cli-reference.md) | Command-line options and usage |
204
+ | [Configuration](./docs/configuration.md) | Environment variables and options |
205
+ | [Conventional Commits](./docs/conventional-commits.md) | Commit message formatting |
206
+ | [Branching Strategy](./docs/branching-strategy.md) | Development workflow |
207
+ | [Version-Centric CI/CD](./docs/version-centric-cicd.md) | Pipeline methodology |
208
+ | [Release Management](./docs/release-management.md) | Managing releases effectively |
209
+ | [Migration Guide](./docs/migration-guide.md) | Transitioning from other approaches |
210
+ | [Best Practices](./docs/best-practices.md) | Recommended patterns |
211
+ | [Troubleshooting](./docs/troubleshooting.md) | Common issues and solutions |
package/docs/README.md CHANGED
@@ -1,45 +1,60 @@
1
1
  # AgileFlow Documentation
2
2
 
3
- Welcome to the AgileFlow documentation! This folder contains detailed guides and explanations for different aspects of the AgileFlow system.
3
+ Welcome to the AgileFlow documentation! AgileFlow is a lightweight, platform-agnostic tool for automatic semantic versioning and changelog generation.
4
+
5
+ ```bash
6
+ npx @logickernel/agileflow
7
+ ```
4
8
 
5
9
  ## Quick Navigation
6
10
 
7
- - **New to AgileFlow?** Start with [Getting Started](./getting-started.md)
8
- - **Want to understand the approach?** Read [Version-Centric CI/CD](./version-centric-cicd.md)
9
- - **Ready to install?** Follow [Installation & Setup](./installation.md)
10
- - **Need help?** Check [Troubleshooting](./troubleshooting.md)
11
+ | I want to... | Read this |
12
+ |--------------|-----------|
13
+ | Get started quickly | [Getting Started](./getting-started.md) |
14
+ | Set up CI/CD integration | [Installation Guide](./installation.md) |
15
+ | Understand the CLI | [CLI Reference](./cli-reference.md) |
16
+ | Learn the methodology | [Version-Centric CI/CD](./version-centric-cicd.md) |
17
+ | Fix an issue | [Troubleshooting](./troubleshooting.md) |
11
18
 
12
- ## Available Documentation
19
+ ## Documentation Index
13
20
 
14
- ### Core Concepts
15
- - **[Version-Centric CI/CD Approach](./version-centric-cicd.md)** - Comprehensive guide to AgileFlow's revolutionary CI/CD paradigm
16
- - **[Installation & Setup](./installation.md)** - Step-by-step installation instructions for different platforms
17
- - **[Conventional Commits](./conventional-commits.md)** - Detailed guide to commit message formatting and types
21
+ ### Getting Started
22
+ - **[Getting Started](./getting-started.md)** — Quick start guide for new users
23
+ - **[Installation Guide](./installation.md)** — Setup for GitHub Actions and GitLab CI
24
+ - **[CLI Reference](./cli-reference.md)** — Commands, options, and examples
18
25
 
19
- ### User Guides
20
- - **[Getting Started](./getting-started.md)** - Quick start guide for new AgileFlow users
21
- - **[Branching Strategy](./branching-strategy.md)** - Complete guide to AgileFlow's branching approach
22
- - **[Release Management](./release-management.md)** - How to manage releases and versions effectively
26
+ ### Core Concepts
27
+ - **[Version-Centric CI/CD](./version-centric-cicd.md)** — The methodology behind AgileFlow
28
+ - **[Branching Strategy](./branching-strategy.md)** — How to structure your Git workflow
29
+ - **[Conventional Commits](./conventional-commits.md)** — Commit message format and version impact
30
+ - **[Release Management](./release-management.md)** — Managing releases and versions
23
31
 
24
32
  ### Reference
25
- - **[CLI Reference](./cli-reference.md)** - Command-line interface documentation
26
- - **[Configuration](./configuration.md)** - Configuration options and environment variables
33
+ - **[Configuration](./configuration.md)** — Environment variables and options
34
+ - **[Best Practices](./best-practices.md)** — Recommended patterns and tips
35
+ - **[Migration Guide](./migration-guide.md)** — Transitioning from other CI/CD approaches
36
+ - **[Troubleshooting](./troubleshooting.md)** — Common issues and solutions
37
+
38
+ ## Platform Support
39
+
40
+ AgileFlow works with any Git repository and provides native integrations for:
27
41
 
28
- ### Advanced Topics
29
- - **[Migration Guide](./migration-guide.md)** - How to transition from traditional CI/CD approaches
30
- - **[Best Practices](./best-practices.md)** - Recommended practices and patterns
31
- - **[Troubleshooting](./troubleshooting.md)** - Common issues and solutions
42
+ - **GitHub Actions** — Uses GitHub API for tag creation
43
+ - **GitLab CI** — Uses GitLab API for tag creation
44
+ - **Any CI/CD** — Native git push for other platforms
32
45
 
33
46
  ## Contributing to Documentation
34
47
 
35
- We welcome contributions to improve our documentation! Please:
48
+ We welcome improvements to our documentation! Please:
36
49
 
37
50
  1. Follow the existing style and tone
38
51
  2. Use clear, concise language
39
- 3. Include practical examples where helpful
52
+ 3. Include practical examples
40
53
  4. Test any code examples or commands
41
- 5. Submit changes via merge requests
54
+ 5. Submit changes via pull/merge requests
42
55
 
43
56
  ## External Resources
44
57
 
45
- - [Main README](../README.md) - Project overview and quick start
58
+ - [Main README](../README.md) — Project overview and quick start
59
+ - [Conventional Commits Specification](https://www.conventionalcommits.org/)
60
+ - [Semantic Versioning Specification](https://semver.org/)