Feature/169 improve readibility of readme

docs/configuration_reference.md

@@ -0,0 +1,107 @@
+# Configuration Reference
+
+This page lists all action inputs and outputs with defaults. Grouped for readability.
+
+## Inputs
+
+| Name | Required | Default | Description |
+|------|----------|---------|-------------|
+| `tag-name` | Yes | – | Target release tag (must already exist). |
+| `from-tag-name` | No | "" | Explicit previous release tag; if empty semantic latest published release is used. |
+| `chapters` | No | "" | YAML list of chapter objects `{ "title": str, "label": str }`. Multiple entries may share a title to aggregate labels. |
+| `hierarchy` | No | `false` | Enable Issue Hierarchy Support. |
+| `published-at` | No | `false` | Use previous release `published_at` timestamp instead of `created_at`. |
+| `skip-release-notes-labels` | No | `skip-release-notes` | Comma‑separated labels that fully exclude issues/PRs. |
+| `warnings` | No | `true` | Toggle Service Chapters generation. |
+| `print-empty-chapters` | No | `true` | Print chapter headings even when empty. |
+| `duplicity-scope` | No | `both` | Where duplicates are allowed: `none`, `custom`, `service`, `both`. Case-insensitive. |
+| `duplicity-icon` | No | `🔔` | One-character icon prefixed on duplicate rows. |
+| `verbose` | No | `false` | Enable verbose (debug) logging. |
+| `release-notes-title` | No | `[Rr]elease [Nn]otes:` | Regex matching the PR body section header for manual notes. First match only. |
+| `coderabbit-support-active` | No | `false` | Enable CodeRabbit fallback when manual notes absent. |
+| `coderabbit-release-notes-title` | No | `Summary by CodeRabbit` | Regex for CodeRabbit summary header. |
+| `coderabbit-summary-ignore-groups` | No | "" | Comma or newline list of group names to discard from CodeRabbit summary. |
+| `row-format-hierarchy-issue` | No | `{type}: _{title}_ {number}` | Template for hierarchy (parent) issue rows. |
+| `row-format-issue` | No | `{type}: {number} _{title}_ developed by {developers} in {pull-requests}` | Template for issue rows. |
+| `row-format-pr` | No | `{number} _{title}_ developed by {developers}` | Template for PR rows. |
+| `row-format-link-pr` | No | `true` | If true adds `PR:` prefix when a PR is listed without an issue. |
+
+> CodeRabbit summaries must already be present in the PR body (produced by your own CI/App setup). This action only parses existing summaries; it does not configure or call CodeRabbit.
+
+### Placeholder Reference
+
+| Context | Placeholders |
+|---------|--------------|
+| Issue | `{type}`, `{number}`, `{title}`, `{author}`, `{assignees}`, `{developers}`, `{pull-requests}` |
+| PR | `{number}`, `{title}`, `{author}`, `{assignees}`, `{developers}` |
+| Hierarchy Issue | `{type}`, `{number}`, `{title}`, `{author}`, `{assignees}`, `{developers}` |
+
+Placeholders are case-insensitive; unknown placeholders are removed silently.
+
+### Chapters Configuration
+Provide chapters as a YAML multi-line string. Each entry must define a `title` and `label`.
+
+```yaml
+with:
+  chapters: |
+    - {"title": "New Features 🎉", "label": "feature"}
+    - {"title": "Bugfixes 🛠", "label": "bug"}
+    - {"title": "Bugfixes 🛠", "label": "error"}  # merges both labels under one heading
+```
+
+Resulting chapter headings are unique by title; labels aggregate.
+
+### Custom Chapters Behavior
+- A record (issue / PR / hierarchy issue) is eligible for a user-defined chapter if it:
+  - Is not skipped (no skip label), and
+  - Contains a change increment (has extracted release notes OR at least one linked merged PR supplying changes), and
+  - Owns at least one label matching any configured chapter label (including implicit issue type label), and
+  - (For hierarchy) ultimately aggregates qualifying sub-issues/PRs.
+- Issue Type is automatically merged into the issue's label set as a lowercase implicit label (e.g. `Epic`, `Feature`, `Bug`, `Task` → `epic`, `feature`, `bug`, `task`). You can reference these directly in `chapters` without adding a duplicate formal label in GitHub.
+- Direct commits are excluded (no labels to match).
+- Multiple entries with identical `title` merge label sets (logical OR across labels under the same heading).
+- Rendering order follows the YAML order of first appearance for each unique title.
+- If `duplicity-scope` excludes `custom`, a record that matched one chapter will not be added to others.
+- Empty chapters: suppressed only when `print-empty-chapters: false`.
+- Duplicity icon is applied per appearance count after all chapters are populated.
+
+### Issue ↔ PR Linking
+Link detection influences chapter population and Service Chapters:
+- GitHub automatically links PRs to issues using closing keywords (e.g. `Fixes #123`, `Closes org/repo#45`). These become closing issue references available through the API.
+- The action also queries GitHub (GraphQL) for closing issue references of each PR (internal implementation) to gather linked issues.
+- If no issue is linked and required metadata is missing, affected PRs can appear in Service Chapters (e.g. *Merged PRs without Issue and User Defined Labels ⚠️*).
+
+### Skip Logic
+Any issue or PR containing at least one label from `skip-release-notes-labels` is entirely excluded from:
+- Release Notes Extraction (manual section parsing)
+- CodeRabbit fallback detection
+- Custom (user-defined) Chapters
+- Service Chapters
+
+### Duplicates
+Controlled by `duplicity-scope` and `duplicity-icon` (see [Duplicity Handling](features/duplicity_handling.md)).
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| `release-notes` | Final Markdown block of release notes (includes Service Chapters if enabled and a Full Changelog link). |
+
+## Quick Selection Guide
+
+| Goal | Recommended Inputs |
+|------|--------------------|
+| Basic release notes | `tag-name`, `chapters` |
+| Restrict time window manually | Add `from-tag-name` |
+| Prefer published timestamp | `published-at: true` |
+| Hide diagnostics | `warnings: false` |
+| Tight output (no empty headings) | `print-empty-chapters: false` |
+| Enforce no duplicates | `duplicity-scope: none` |
+| Enable hierarchy rollups | `hierarchy: true` |
+| Use AI fallback | `coderabbit-support-active: true` |
+
+## Related Pages
+- [Feature Tutorials](../README.md#feature-tutorials)
+- [Release Notes Extraction](features/release_notes_extraction.md)
+- [Service Chapters](features/service_chapters.md)
+- [Duplicity Handling](features/duplicity_handling.md)

docs/features/coderabbit_integration.md

@@ -0,0 +1,64 @@
+# Feature: CodeRabbit Integration
+
+## Purpose
+Provide an automatic fallback summary for pull requests that lack an explicit Release Notes section. Uses a CodeRabbit-generated summary block when available and configured, reducing manual effort and minimizing empty chapters.
+
+> NOTE: This action only CONSUMES a CodeRabbit summary already present in the PR body. It does NOT configure, invoke, or authenticate CodeRabbit itself. Any CodeRabbit workflow, app installation, or settings are managed outside of this action.
+
+## How It Works
+- Activation is controlled by input `coderabbit-support-active` (default: `false`). When `false`, no CodeRabbit parsing occurs.
+- If Release Notes Extraction fails to find a matching section (or yields zero valid bullet lines), the action searches for a section whose heading matches `coderabbit-release-notes-title` (regex, default: `Summary by CodeRabbit`).
+- The detected summary text is converted into bullet entries using existing bullet list markers (`-`, `*`, `+`) found inside the summary block.
+- Groups listed in `coderabbit-summary-ignore-groups` are removed. Delimiters supported: comma (",") OR newline. The parser picks comma if present; otherwise splits by newline.
+- If both explicit release notes AND a CodeRabbit section exist, only the explicit release notes are used (no merge; strict fallback behavior).
+- Skip Labels still apply: PRs or issues labeled with any `skip-release-notes-labels` value are ignored entirely.
+
+## Configuration
+```yaml
+- name: Generate Release Notes
+  id: release_notes_scrapper
+  uses: AbsaOSS/generate-release-notes@v1
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  with:
+    tag-name: "v1.2.0"
+    chapters: |
+      - {"title": "New Features 🎉", "label": "feature"}
+    coderabbit-support-active: true
+    coderabbit-release-notes-title: "Summary by CodeRabbit"   # optional regex override
+    coderabbit-summary-ignore-groups: "Chore,Internal"        # comma or newline separated list
+    release-notes-title: "[Rr]elease [Nn]otes:"               # shown for clarity
+```
+
+### PR Body Example (no explicit release notes)
+```markdown
+Implementation details...
+
+Summary by CodeRabbit
+- Add MFA enrollment flow
+- Improve cache invalidation
+
+Additional notes.
+```
+
+## Example Result (fallback in effect)
+```markdown
+### New Features 🎉
+- #233 _Add MFA enrollment flow_ developed by @alice in #234
+  - Add MFA enrollment flow
+  - Improve cache invalidation
+```
+(Exact formatting depends on Custom Row Formats and whether an issue is linked.)
+
+## Limitations
+- Only activates when no valid explicit release notes section is found.
+- Relies on predictable heading text; modified headings may need a custom `coderabbit-release-notes-title` regex.
+- Group filtering requires consistent group naming within the CodeRabbit summary output.
+- Does not merge with partially present manual notes—manual notes have precedence.
+
+## Related Features
+- [Release Notes Extraction](./release_notes_extraction.md) – primary mechanism; CodeRabbit is only a fallback.
+- [Skip Labels](./skip_labels.md) – can exclude PRs entirely (applies before fallback).
+- [Duplicity Handling](./duplicity_handling.md) – marks duplicates across chapters.
+
+← [Back to Feature Tutorials](../../README.md#feature-tutorials)

docs/features/custom_chapters.md

@@ -0,0 +1,64 @@
+# Feature: Custom Chapters
+
+## Purpose
+Map issue and PR labels to human-friendly chapter titles. Lets teams group multiple labels under a single heading and control output order without modifying repository label taxonomy.
+
+## How It Works
+- Input `chapters` is a YAML list; each entry contains `title` + `label`.
+- Multiple entries with the same `title` aggregate labels into one chapter (logical OR).
+- Records qualify when: not skipped, contain a change increment (at least one linked merged PR), and have ≥1 matching label (explicit or implicit Issue Type label).
+  - Issue Type is automatically merged as a lowercase implicit label (e.g. `Epic` → `epic`, `Feature` → `feature`, `Bug` → `bug`, `Task` → `task`). You can reference these directly in `chapters` without creating extra labels in the repository.
+- Direct commits are ignored (no labels) and appear only in Service Chapters if relevant.
+- Duplicates across chapters depend on `duplicity-scope` (see Duplicity Handling). If disallowed, first match wins.
+- Empty chapters printed only when `print-empty-chapters: true`.
+
+## Configuration
+```yaml
+- name: Generate Release Notes
+  id: release_notes_scrapper
+  uses: AbsaOSS/generate-release-notes@v1
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  with:
+    tag-name: "v2.1.0"
+    chapters: |
+      - {"title": "New Features 🎉", "label": "feature"}
+      - {"title": "New Features 🎉", "label": "enhancement"}
+      - {"title": "Bugfixes 🛠", "label": "bug"}
+      - {"title": "Epics", "label": "epic"}          # using implicit issue type label
+    duplicity-scope: "custom"
+    print-empty-chapters: true
+```
+
+## Example Result
+```markdown
+### New Features 🎉
+- #410 _Add inline diff viewer_ developed by @alice in #415
+
+### Bugfixes 🛠
+- #412 _Fix cache stampede_ developed by @bob in #418
+```
+(Multiple labels under the same title unify into one heading.)
+
+## FAQ
+**Why didn’t my issue appear in any chapter?**
+- It has a skip label (see [Skip Labels](./skip_labels.md)).
+- It has no change increment (no merged PR linked to it).
+- Its labels (including implicit issue type) don’t match any configured chapter labels.
+- It’s still open and hierarchy/Service Chapters logic filtered it (for some diagnostics scenarios) but not eligible for user chapters.
+- Duplicates disabled (`duplicity-scope` excludes `custom`) and it already appeared under an earlier matching chapter.
+
+**How do I group by issue types without adding labels?**  Use the lowercase implicit type (`epic`, `feature`, `bug`, `task`) in `chapters`.
+
+**Why is a chapter heading empty?** Either no records qualified or they were all skipped/excluded by duplicity scope. Disable empty headings via `print-empty-chapters: false`.
+
+**Can a PR-only item appear without an issue?** Yes—if its labels match a chapter. The line will format using the PR row template.
+
+## Related Features
+- [Duplicity Handling](./duplicity_handling.md) – governs multi-chapter visibility.
+- [Release Notes Extraction](./release_notes_extraction.md) – provides the change increment lines.
+- [Skip Labels](./skip_labels.md) – excluded records never reach chapters.
+- [Custom Row Formats](./custom_row_formats.md) – adjusts row templates.
+- [Service Chapters](./service_chapters.md) – diagnostics separate from user-defined chapters.
+
+← [Back to Feature Tutorials](../../README.md#feature-tutorials)

docs/features/custom_row_formats.md

@@ -0,0 +1,51 @@
+# Feature: Custom Row Formats
+
+## Purpose
+Customize how individual issue, PR, and hierarchy issue lines are rendered in the release notes. Ensures output matches team conventions without post-processing.
+
+## How It Works
+- Controlled by inputs:
+  - `row-format-hierarchy-issue`
+  - `row-format-issue`
+  - `row-format-pr`
+  - `row-format-link-pr` (boolean controlling prefix `PR:` presence for standalone PR links)
+- Placeholders are case-insensitive; unknown placeholders are removed.
+- Available placeholders:
+  - Hierarchy issue rows: `{type}`, `{number}`, `{title}`, `{author}`, `{assignees}`, `{developers}`
+  - Issue rows: `{type}`, `{number}`, `{title}`, `{author}`, `{assignees}`, `{developers}`, `{pull-requests}`
+  - PR rows: `{number}`, `{title}`, `{author}`, `{assignees}`, `{developers}`
+- Duplicity icon (if triggered) is prefixed before the formatted row.
+
+## Configuration
+```yaml
+- name: Generate Release Notes
+  id: release_notes_scrapper
+  uses: AbsaOSS/generate-release-notes@v1
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  with:
+    tag-name: "v4.0.0"
+    chapters: |
+      - {"title": "Features", "label": "feature"}
+    row-format-hierarchy-issue: "{type}: _{title}_ {number}"
+    row-format-issue: "{type}: {number} _{title}_ developed by {developers} in {pull-requests}"
+    row-format-pr: "{number} _{title}_ developed by {developers}"
+    row-format-link-pr: true  # include PR: prefix when issue not linked
+```
+
+## Example Result
+
+```markdown
+### Features
+- Task: #500 _Add inline diff viewer_ developed by @alice in #501
+- PR: #505 _Add inline diff viewer_ developed by @kevin
+```
+
+(Formatting reflects the provided custom templates.)
+
+## Related Features
+- [Duplicity Handling](./duplicity_handling.md) – may add icon before formatted line.
+- [Issue Hierarchy Support](./issue_hierarchy_support.md) – hierarchy rows use their own format.
+
+← [Back to Feature Tutorials](../../README.md#feature-tutorials)
+

docs/features/date_selection.md

@@ -0,0 +1,44 @@
+# Feature: Date Selection
+
+## Purpose
+Choose which timestamp from the previous release defines the cutoff boundary (the "since" moment) for included issues, PRs, and commits. Provides control for teams that publish releases later than they create them.
+
+## How It Works
+- Input `published-at` (boolean, default `false`).
+- When `published-at: true`, the previous release’s `published_at` timestamp is used.
+- When `false`, the previous release’s `created_at` timestamp is used.
+- If no prior release exists (first release), all issues are fetched without a filtration.
+
+## Configuration
+```yaml
+- name: Generate Release Notes
+  id: release_notes_scrapper
+  uses: AbsaOSS/generate-release-notes@v1
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  with:
+    tag-name: "v1.6.0"
+    from-tag-name: "v1.5.0"  # defines the previous release
+    published-at: true        # use published_at instead of created_at
+    chapters: |
+      - {"title": "Features", "label": "feature"}
+      - {"title": "Fixes", "label": "bug"}
+```
+
+## Example Result
+```markdown
+### Features
+- #360 _Add audit event sink_ developed by @dev in #365
+
+#### Full Changelog
+https://github.com/org/repo/compare/v1.5.0...v1.6.0
+```
+(The included only records occurred after the chosen previous release timestamp.)
+
+## Related Features
+- [Tag Range Selection](./tag_range.md) – defines which releases bound the window.
+- [Service Chapters](./service_chapters.md) – uses same time window for diagnostics.
+- [Release Notes Extraction](./release_notes_extraction.md) – only scans PRs within the window.
+
+← [Back to Feature Tutorials](../../README.md#feature-tutorials)
+

docs/features/duplicity_handling.md

@@ -0,0 +1,53 @@
+# Feature: Duplicity Handling
+
+## Purpose
+Control whether the same record (issue / PR / hierarchy issue / commit) can appear in multiple chapters and visually mark duplicates. Prevents clutter while still allowing intentional multi-label visibility.
+
+## How It Works
+- Input `duplicity-scope` defines where duplicates are allowed: `none`, `custom`, `service`, `both` (case-insensitive).
+- When a record matches multiple user-defined chapters and scope permits (`custom` or `both`), it can appear more than once.
+- Service Chapters obey the same rule: duplicates allowed only if scope includes `service` or `both`.
+- A duplicate (present in >1 chapter) is prefixed by the single-character icon from `duplicity-icon` (default: 🔔) when rendered.
+- If duplicates are disallowed for a given group, additional occurrences are skipped silently (no placeholder or warning).
+
+### Choosing `duplicity-scope`
+| Value | Custom Chapters Duplicates | Service Chapters Duplicates | Icon Applied (if >1 appearance) | Typical Use Case |
+|-------|----------------------------|------------------------------|---------------------------------|------------------|
+| `none` | No | No | Never (only single appearance) | Strict single-source classification |
+| `custom` | Yes | No | Yes (in custom) | Emphasize multi-label themes; keep diagnostics lean |
+| `service` | No | Yes | Yes (in service) | Observe all diagnostic contexts; keep user chapters clean |
+| `both` | Yes | Yes | Yes | Maximum visibility across all chapter types |
+
+## Configuration
+```yaml
+- name: Generate Release Notes
+  id: release_notes_scrapper
+  uses: AbsaOSS/generate-release-notes@v1
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  with:
+    tag-name: "v3.0.0"
+    chapters: |
+      - {"title": "Features", "label": "feature"}
+      - {"title": "Quality", "label": "quality"}
+    duplicity-scope: "both"   # none|custom|service|both
+    duplicity-icon: "🔔"       # must be exactly one character
+```
+
+## Example Result
+```markdown
+### Features
+🔔 #410 _Improve cache layer_ developed by @alice in #415
+
+### Quality
+🔔 #410 _Improve cache layer_ developed by @alice in #415
+```
+(Icon appears because the same record appeared in two chapters with scope permitting duplicates.)
+
+## Related Features
+- [Service Chapters](./service_chapters.md) – also affected by duplicity scope.
+- [Custom Row Formats](./custom_row_formats.md) – icon is prefixed before formatted line.
+- [Skip Labels](./skip_labels.md) – skipped records never produce duplicates.
+- [Release Notes Extraction](./release_notes_extraction.md) – determines which records have change increments.
+
+← [Back to Feature Tutorials](../../README.md#feature-tutorials)