Skip to content

Commit 80b27be

Browse files
miroslavpojermiroslavpojer
authored
Feature/169 improve readibility of readme (#193)
* #169 - Improve readibility of README - Updated root README.md file. - Create new structure of features tutorials. - Introduces new set of single feature doc pages. - Added new output example to show hierarchy.
1 parent 3bbce0b commit 80b27be

16 files changed

+1002
-301
lines changed

‎README.md‎

Lines changed: 163 additions & 301 deletions
Large diffs are not rendered by default.

‎docs/configuration_reference.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# Configuration Reference
2+
3+
This page lists all action inputs and outputs with defaults. Grouped for readability.
4+
5+
## Inputs
6+
7+
| Name | Required | Default | Description |
8+
|------|----------|---------|-------------|
9+
| `tag-name` | Yes | – | Target release tag (must already exist). |
10+
| `from-tag-name` | No | "" | Explicit previous release tag; if empty semantic latest published release is used. |
11+
| `chapters` | No | "" | YAML list of chapter objects `{ "title": str, "label": str }`. Multiple entries may share a title to aggregate labels. |
12+
| `hierarchy` | No | `false` | Enable Issue Hierarchy Support. |
13+
| `published-at` | No | `false` | Use previous release `published_at` timestamp instead of `created_at`. |
14+
| `skip-release-notes-labels` | No | `skip-release-notes` | Comma‑separated labels that fully exclude issues/PRs. |
15+
| `warnings` | No | `true` | Toggle Service Chapters generation. |
16+
| `print-empty-chapters` | No | `true` | Print chapter headings even when empty. |
17+
| `duplicity-scope` | No | `both` | Where duplicates are allowed: `none`, `custom`, `service`, `both`. Case-insensitive. |
18+
| `duplicity-icon` | No | `🔔` | One-character icon prefixed on duplicate rows. |
19+
| `verbose` | No | `false` | Enable verbose (debug) logging. |
20+
| `release-notes-title` | No | `[Rr]elease [Nn]otes:` | Regex matching the PR body section header for manual notes. First match only. |
21+
| `coderabbit-support-active` | No | `false` | Enable CodeRabbit fallback when manual notes absent. |
22+
| `coderabbit-release-notes-title` | No | `Summary by CodeRabbit` | Regex for CodeRabbit summary header. |
23+
| `coderabbit-summary-ignore-groups` | No | "" | Comma or newline list of group names to discard from CodeRabbit summary. |
24+
| `row-format-hierarchy-issue` | No | `{type}: _{title}_ {number}` | Template for hierarchy (parent) issue rows. |
25+
| `row-format-issue` | No | `{type}: {number} _{title}_ developed by {developers} in {pull-requests}` | Template for issue rows. |
26+
| `row-format-pr` | No | `{number} _{title}_ developed by {developers}` | Template for PR rows. |
27+
| `row-format-link-pr` | No | `true` | If true adds `PR:` prefix when a PR is listed without an issue. |
28+
29+
> 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.
30+
31+
### Placeholder Reference
32+
33+
| Context | Placeholders |
34+
|---------|--------------|
35+
| Issue | `{type}`, `{number}`, `{title}`, `{author}`, `{assignees}`, `{developers}`, `{pull-requests}` |
36+
| PR | `{number}`, `{title}`, `{author}`, `{assignees}`, `{developers}` |
37+
| Hierarchy Issue | `{type}`, `{number}`, `{title}`, `{author}`, `{assignees}`, `{developers}` |
38+
39+
Placeholders are case-insensitive; unknown placeholders are removed silently.
40+
41+
### Chapters Configuration
42+
Provide chapters as a YAML multi-line string. Each entry must define a `title` and `label`.
43+
44+
```yaml
45+
with:
46+
chapters: |
47+
- {"title": "New Features 🎉", "label": "feature"}
48+
- {"title": "Bugfixes 🛠", "label": "bug"}
49+
- {"title": "Bugfixes 🛠", "label": "error"} # merges both labels under one heading
50+
```
51+
52+
Resulting chapter headings are unique by title; labels aggregate.
53+
54+
### Custom Chapters Behavior
55+
- A record (issue / PR / hierarchy issue) is eligible for a user-defined chapter if it:
56+
- Is not skipped (no skip label), and
57+
- Contains a change increment (has extracted release notes OR at least one linked merged PR supplying changes), and
58+
- Owns at least one label matching any configured chapter label (including implicit issue type label), and
59+
- (For hierarchy) ultimately aggregates qualifying sub-issues/PRs.
60+
- 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.
61+
- Direct commits are excluded (no labels to match).
62+
- Multiple entries with identical `title` merge label sets (logical OR across labels under the same heading).
63+
- Rendering order follows the YAML order of first appearance for each unique title.
64+
- If `duplicity-scope` excludes `custom`, a record that matched one chapter will not be added to others.
65+
- Empty chapters: suppressed only when `print-empty-chapters: false`.
66+
- Duplicity icon is applied per appearance count after all chapters are populated.
67+
68+
### Issue ↔ PR Linking
69+
Link detection influences chapter population and Service Chapters:
70+
- 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.
71+
- The action also queries GitHub (GraphQL) for closing issue references of each PR (internal implementation) to gather linked issues.
72+
- 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 ⚠️*).
73+
74+
### Skip Logic
75+
Any issue or PR containing at least one label from `skip-release-notes-labels` is entirely excluded from:
76+
- Release Notes Extraction (manual section parsing)
77+
- CodeRabbit fallback detection
78+
- Custom (user-defined) Chapters
79+
- Service Chapters
80+
81+
### Duplicates
82+
Controlled by `duplicity-scope` and `duplicity-icon` (see [Duplicity Handling](features/duplicity_handling.md)).
83+
84+
## Outputs
85+
86+
| Name | Description |
87+
|------|-------------|
88+
| `release-notes` | Final Markdown block of release notes (includes Service Chapters if enabled and a Full Changelog link). |
89+
90+
## Quick Selection Guide
91+
92+
| Goal | Recommended Inputs |
93+
|------|--------------------|
94+
| Basic release notes | `tag-name`, `chapters` |
95+
| Restrict time window manually | Add `from-tag-name` |
96+
| Prefer published timestamp | `published-at: true` |
97+
| Hide diagnostics | `warnings: false` |
98+
| Tight output (no empty headings) | `print-empty-chapters: false` |
99+
| Enforce no duplicates | `duplicity-scope: none` |
100+
| Enable hierarchy rollups | `hierarchy: true` |
101+
| Use AI fallback | `coderabbit-support-active: true` |
102+
103+
## Related Pages
104+
- [Feature Tutorials](../README.md#feature-tutorials)
105+
- [Release Notes Extraction](features/release_notes_extraction.md)
106+
- [Service Chapters](features/service_chapters.md)
107+
- [Duplicity Handling](features/duplicity_handling.md)

‎docs/features/coderabbit_integration.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Feature: CodeRabbit Integration
2+
3+
## Purpose
4+
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.
5+
6+
> 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.
7+
8+
## How It Works
9+
- Activation is controlled by input `coderabbit-support-active` (default: `false`). When `false`, no CodeRabbit parsing occurs.
10+
- 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`).
11+
- The detected summary text is converted into bullet entries using existing bullet list markers (`-`, `*`, `+`) found inside the summary block.
12+
- Groups listed in `coderabbit-summary-ignore-groups` are removed. Delimiters supported: comma (",") OR newline. The parser picks comma if present; otherwise splits by newline.
13+
- If both explicit release notes AND a CodeRabbit section exist, only the explicit release notes are used (no merge; strict fallback behavior).
14+
- Skip Labels still apply: PRs or issues labeled with any `skip-release-notes-labels` value are ignored entirely.
15+
16+
## Configuration
17+
```yaml
18+
- name: Generate Release Notes
19+
id: release_notes_scrapper
20+
uses: AbsaOSS/generate-release-notes@v1
21+
env:
22+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
23+
with:
24+
tag-name: "v1.2.0"
25+
chapters: |
26+
- {"title": "New Features 🎉", "label": "feature"}
27+
coderabbit-support-active: true
28+
coderabbit-release-notes-title: "Summary by CodeRabbit" # optional regex override
29+
coderabbit-summary-ignore-groups: "Chore,Internal" # comma or newline separated list
30+
release-notes-title: "[Rr]elease [Nn]otes:" # shown for clarity
31+
```
32+
33+
### PR Body Example (no explicit release notes)
34+
```markdown
35+
Implementation details...
36+
37+
Summary by CodeRabbit
38+
- Add MFA enrollment flow
39+
- Improve cache invalidation
40+
41+
Additional notes.
42+
```
43+
44+
## Example Result (fallback in effect)
45+
```markdown
46+
### New Features 🎉
47+
- #233 _Add MFA enrollment flow_ developed by @alice in #234
48+
- Add MFA enrollment flow
49+
- Improve cache invalidation
50+
```
51+
(Exact formatting depends on Custom Row Formats and whether an issue is linked.)
52+
53+
## Limitations
54+
- Only activates when no valid explicit release notes section is found.
55+
- Relies on predictable heading text; modified headings may need a custom `coderabbit-release-notes-title` regex.
56+
- Group filtering requires consistent group naming within the CodeRabbit summary output.
57+
- Does not merge with partially present manual notes—manual notes have precedence.
58+
59+
## Related Features
60+
- [Release Notes Extraction](./release_notes_extraction.md) – primary mechanism; CodeRabbit is only a fallback.
61+
- [Skip Labels](./skip_labels.md) – can exclude PRs entirely (applies before fallback).
62+
- [Duplicity Handling](./duplicity_handling.md) – marks duplicates across chapters.
63+
64+
← [Back to Feature Tutorials](../../README.md#feature-tutorials)

‎docs/features/custom_chapters.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Feature: Custom Chapters
2+
3+
## Purpose
4+
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.
5+
6+
## How It Works
7+
- Input `chapters` is a YAML list; each entry contains `title` + `label`.
8+
- Multiple entries with the same `title` aggregate labels into one chapter (logical OR).
9+
- 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).
10+
- 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.
11+
- Direct commits are ignored (no labels) and appear only in Service Chapters if relevant.
12+
- Duplicates across chapters depend on `duplicity-scope` (see Duplicity Handling). If disallowed, first match wins.
13+
- Empty chapters printed only when `print-empty-chapters: true`.
14+
15+
## Configuration
16+
```yaml
17+
- name: Generate Release Notes
18+
id: release_notes_scrapper
19+
uses: AbsaOSS/generate-release-notes@v1
20+
env:
21+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
22+
with:
23+
tag-name: "v2.1.0"
24+
chapters: |
25+
- {"title": "New Features 🎉", "label": "feature"}
26+
- {"title": "New Features 🎉", "label": "enhancement"}
27+
- {"title": "Bugfixes 🛠", "label": "bug"}
28+
- {"title": "Epics", "label": "epic"} # using implicit issue type label
29+
duplicity-scope: "custom"
30+
print-empty-chapters: true
31+
```
32+
33+
## Example Result
34+
```markdown
35+
### New Features 🎉
36+
- #410 _Add inline diff viewer_ developed by @alice in #415
37+
38+
### Bugfixes 🛠
39+
- #412 _Fix cache stampede_ developed by @bob in #418
40+
```
41+
(Multiple labels under the same title unify into one heading.)
42+
43+
## FAQ
44+
**Why didn’t my issue appear in any chapter?**
45+
- It has a skip label (see [Skip Labels](./skip_labels.md)).
46+
- It has no change increment (no merged PR linked to it).
47+
- Its labels (including implicit issue type) don’t match any configured chapter labels.
48+
- It’s still open and hierarchy/Service Chapters logic filtered it (for some diagnostics scenarios) but not eligible for user chapters.
49+
- Duplicates disabled (`duplicity-scope` excludes `custom`) and it already appeared under an earlier matching chapter.
50+
51+
**How do I group by issue types without adding labels?** Use the lowercase implicit type (`epic`, `feature`, `bug`, `task`) in `chapters`.
52+
53+
**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`.
54+
55+
**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.
56+
57+
## Related Features
58+
- [Duplicity Handling](./duplicity_handling.md) – governs multi-chapter visibility.
59+
- [Release Notes Extraction](./release_notes_extraction.md) – provides the change increment lines.
60+
- [Skip Labels](./skip_labels.md) – excluded records never reach chapters.
61+
- [Custom Row Formats](./custom_row_formats.md) – adjusts row templates.
62+
- [Service Chapters](./service_chapters.md) – diagnostics separate from user-defined chapters.
63+
64+
← [Back to Feature Tutorials](../../README.md#feature-tutorials)

‎docs/features/custom_row_formats.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Feature: Custom Row Formats
2+
3+
## Purpose
4+
Customize how individual issue, PR, and hierarchy issue lines are rendered in the release notes. Ensures output matches team conventions without post-processing.
5+
6+
## How It Works
7+
- Controlled by inputs:
8+
- `row-format-hierarchy-issue`
9+
- `row-format-issue`
10+
- `row-format-pr`
11+
- `row-format-link-pr` (boolean controlling prefix `PR:` presence for standalone PR links)
12+
- Placeholders are case-insensitive; unknown placeholders are removed.
13+
- Available placeholders:
14+
- Hierarchy issue rows: `{type}`, `{number}`, `{title}`, `{author}`, `{assignees}`, `{developers}`
15+
- Issue rows: `{type}`, `{number}`, `{title}`, `{author}`, `{assignees}`, `{developers}`, `{pull-requests}`
16+
- PR rows: `{number}`, `{title}`, `{author}`, `{assignees}`, `{developers}`
17+
- Duplicity icon (if triggered) is prefixed before the formatted row.
18+
19+
## Configuration
20+
```yaml
21+
- name: Generate Release Notes
22+
id: release_notes_scrapper
23+
uses: AbsaOSS/generate-release-notes@v1
24+
env:
25+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
26+
with:
27+
tag-name: "v4.0.0"
28+
chapters: |
29+
- {"title": "Features", "label": "feature"}
30+
row-format-hierarchy-issue: "{type}: _{title}_ {number}"
31+
row-format-issue: "{type}: {number} _{title}_ developed by {developers} in {pull-requests}"
32+
row-format-pr: "{number} _{title}_ developed by {developers}"
33+
row-format-link-pr: true # include PR: prefix when issue not linked
34+
```
35+
36+
## Example Result
37+
38+
```markdown
39+
### Features
40+
- Task: #500 _Add inline diff viewer_ developed by @alice in #501
41+
- PR: #505 _Add inline diff viewer_ developed by @kevin
42+
```
43+
44+
(Formatting reflects the provided custom templates.)
45+
46+
## Related Features
47+
- [Duplicity Handling](./duplicity_handling.md) – may add icon before formatted line.
48+
- [Issue Hierarchy Support](./issue_hierarchy_support.md) – hierarchy rows use their own format.
49+
50+
← [Back to Feature Tutorials](../../README.md#feature-tutorials)
51+

‎docs/features/date_selection.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Feature: Date Selection
2+
3+
## Purpose
4+
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.
5+
6+
## How It Works
7+
- Input `published-at` (boolean, default `false`).
8+
- When `published-at: true`, the previous release’s `published_at` timestamp is used.
9+
- When `false`, the previous release’s `created_at` timestamp is used.
10+
- If no prior release exists (first release), all issues are fetched without a filtration.
11+
12+
## Configuration
13+
```yaml
14+
- name: Generate Release Notes
15+
id: release_notes_scrapper
16+
uses: AbsaOSS/generate-release-notes@v1
17+
env:
18+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
19+
with:
20+
tag-name: "v1.6.0"
21+
from-tag-name: "v1.5.0" # defines the previous release
22+
published-at: true # use published_at instead of created_at
23+
chapters: |
24+
- {"title": "Features", "label": "feature"}
25+
- {"title": "Fixes", "label": "bug"}
26+
```
27+
28+
## Example Result
29+
```markdown
30+
### Features
31+
- #360 _Add audit event sink_ developed by @dev in #365
32+
33+
#### Full Changelog
34+
https://github.com/org/repo/compare/v1.5.0...v1.6.0
35+
```
36+
(The included only records occurred after the chosen previous release timestamp.)
37+
38+
## Related Features
39+
- [Tag Range Selection](./tag_range.md) – defines which releases bound the window.
40+
- [Service Chapters](./service_chapters.md) – uses same time window for diagnostics.
41+
- [Release Notes Extraction](./release_notes_extraction.md) – only scans PRs within the window.
42+
43+
← [Back to Feature Tutorials](../../README.md#feature-tutorials)
44+

‎docs/features/duplicity_handling.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Feature: Duplicity Handling
2+
3+
## Purpose
4+
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.
5+
6+
## How It Works
7+
- Input `duplicity-scope` defines where duplicates are allowed: `none`, `custom`, `service`, `both` (case-insensitive).
8+
- When a record matches multiple user-defined chapters and scope permits (`custom` or `both`), it can appear more than once.
9+
- Service Chapters obey the same rule: duplicates allowed only if scope includes `service` or `both`.
10+
- A duplicate (present in >1 chapter) is prefixed by the single-character icon from `duplicity-icon` (default: 🔔) when rendered.
11+
- If duplicates are disallowed for a given group, additional occurrences are skipped silently (no placeholder or warning).
12+
13+
### Choosing `duplicity-scope`
14+
| Value | Custom Chapters Duplicates | Service Chapters Duplicates | Icon Applied (if >1 appearance) | Typical Use Case |
15+
|-------|----------------------------|------------------------------|---------------------------------|------------------|
16+
| `none` | No | No | Never (only single appearance) | Strict single-source classification |
17+
| `custom` | Yes | No | Yes (in custom) | Emphasize multi-label themes; keep diagnostics lean |
18+
| `service` | No | Yes | Yes (in service) | Observe all diagnostic contexts; keep user chapters clean |
19+
| `both` | Yes | Yes | Yes | Maximum visibility across all chapter types |
20+
21+
## Configuration
22+
```yaml
23+
- name: Generate Release Notes
24+
id: release_notes_scrapper
25+
uses: AbsaOSS/generate-release-notes@v1
26+
env:
27+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
28+
with:
29+
tag-name: "v3.0.0"
30+
chapters: |
31+
- {"title": "Features", "label": "feature"}
32+
- {"title": "Quality", "label": "quality"}
33+
duplicity-scope: "both" # none|custom|service|both
34+
duplicity-icon: "🔔" # must be exactly one character
35+
```
36+
37+
## Example Result
38+
```markdown
39+
### Features
40+
🔔 #410 _Improve cache layer_ developed by @alice in #415
41+
42+
### Quality
43+
🔔 #410 _Improve cache layer_ developed by @alice in #415
44+
```
45+
(Icon appears because the same record appeared in two chapters with scope permitting duplicates.)
46+
47+
## Related Features
48+
- [Service Chapters](./service_chapters.md) – also affected by duplicity scope.
49+
- [Custom Row Formats](./custom_row_formats.md) – icon is prefixed before formatted line.
50+
- [Skip Labels](./skip_labels.md) – skipped records never produce duplicates.
51+
- [Release Notes Extraction](./release_notes_extraction.md) – determines which records have change increments.
52+
53+
← [Back to Feature Tutorials](../../README.md#feature-tutorials)

0 commit comments

Comments
 (0)