|
1 | | -# generate-release-notes |
2 | | -Efficiently automate your release note generation with 'generate-release-notes'. This tool scans your target GitHub repository's issues, sorting and organizing them into well-formatted release notes. Perfect for maintaining a streamlined and organized release process. |
| 1 | +# Generate Release Notes Action |
| 2 | + |
| 3 | +This GitHub Action automatically generates release notes for a given release tag by categorizing contributions into user-defined chapters based on labels. It streamlines the process of documenting new features, bug fixes, and breaking changes in your project releases. |
| 4 | + |
| 5 | +## Motivation |
| 6 | + |
| 7 | +Generate Release Notes action is dedicated to enhance the quality and organization of project documentation. Its primary purpose is to categorize release notes according to various labels, perfectly aligning with the unique organizational needs of each project. In addition, it offers robust support for acknowledging the efforts of contributors, thereby fostering a sense of recognition and appreciation within the team. Another noteworthy feature of this tool is its capability to detect potential gaps in documentation, ensuring that release notes are comprehensive and leave no stone unturned. Well maintained release notes are a vital component in maintaining high-quality, meticulously organized documentation, which is indispensable in the development process. This repository reflects our commitment to excellence in project documentation and team collaboration. |
| 8 | + |
| 9 | +## Setup and Usage |
| 10 | + |
| 11 | +### Prerequisites |
| 12 | + |
| 13 | +Before we begin, ensure you have a GitHub Token with permission to fetch repository data such as Issues and Pull Requests. |
| 14 | + |
| 15 | +### Adding the Action to Your Workflow |
| 16 | + |
| 17 | +Add the following step to your GitHub workflow: |
| 18 | + |
| 19 | +```yaml |
| 20 | +- name: Generate Release Notes |
| 21 | + id: generate_release_notes |
| 22 | + |
| 23 | + with: |
| 24 | + github_token: ${{ secrets.GITHUB_TOKEN }} |
| 25 | + chapters: '[ |
| 26 | + {"title": "Breaking Changes 💥", "label": "breaking-change"}, |
| 27 | + {"title": "New Features 🎉", "label": "enhancement"}, |
| 28 | + {"title": "Bugfixes 🛠", "label": "bugfix"} |
| 29 | + ]' |
| 30 | + warnings: true |
| 31 | + |
| 32 | +- name: Print generated Release notes |
| 33 | + run: | |
| 34 | + echo "Generated Release Notes:" |
| 35 | + echo "${{ steps.generate_release_notes.outputs.releaseNotes }}" |
| 36 | +``` |
| 37 | +
|
| 38 | +### Configure the Action |
| 39 | +Configure the action by customizing the following parameters based on your needs: |
| 40 | +
|
| 41 | +- **github_token** (required): Your GitHub token for authentication. Store it as a secret and reference it in the workflow file as secrets.GITHUB_TOKEN. |
| 42 | +- **chapters** (required): A JSON string defining chapters and corresponding labels for categorization. Each chapter, like "Breaking Changes", "New Features", and "Bugfixes", should have a title and a label matching your GitHub issues and PRs. |
| 43 | +- **warnings** (optional): Set to true to enable warnings in the release notes. These warnings identify issues without release notes, without user-defined labels, or without associated pull requests, and PRs without linked issues. Defaults to false if not specified. |
| 44 | +
|
| 45 | +### Build the Action: |
| 46 | +If you need to build the action locally: |
| 47 | +
|
| 48 | +```bash |
| 49 | +npm install |
| 50 | +npm run build |
| 51 | +``` |
| 52 | + |
| 53 | +Then, commit action.yml and dist/index.js to your repository. |
| 54 | + |
| 55 | +### Release Notes Extraction Process |
| 56 | + |
| 57 | +This action requires that your GitHub issues include comments with specific release notes. Here's how it works: |
| 58 | + |
| 59 | +#### Extraction Method |
| 60 | +The action scans through comments on each closed issue since the last release. It identifies comments that follow the specified format and extracts the content as part of the release notes. |
| 61 | + |
| 62 | +**Note**: The time considered for the previous release is based on its creation time. This means that the action will look for issues closed after the creation time of the most recent release to ensure that all relevant updates since that release are included. |
| 63 | + |
| 64 | +#### Comment Format |
| 65 | +For an issue's contributions to be included in the release notes, it must contain a comment starting with "Release Notes" followed by the note content. This comment is typically added by the contributors. |
| 66 | +``` |
| 67 | +Release Notes |
| 68 | +- This update introduces a new caching mechanism that improves performance by 20%. |
| 69 | +``` |
| 70 | + |
| 71 | +#### Contributors Mention |
| 72 | +Along with the release note content, the action also gathers a list of contributors for each issue. This includes issue assignees and authors of linked pull requests' commits, providing acknowledgment for their contributions in the release notes. |
| 73 | + |
| 74 | +#### Handling Multiple PRs |
| 75 | +If an issue is linked to multiple PRs, the action fetches and aggregates contributions from all linked PRs. |
| 76 | + |
| 77 | +#### No Release Notes Found |
| 78 | +If no valid "Release Notes" comment is found in an issue, it will be marked accordingly. This helps maintainers quickly identify which issues need attention for documentation. |
| 79 | + |
| 80 | +#### Warnings |
| 81 | +If the `warnings` option is enabled in the action's configuration, the release notes will include sections that highlight possible issues. |
| 82 | + |
| 83 | +The action includes four specific warning chapters to highlight potential areas of improvement in release documentation. Each chapter serves a distinct purpose: |
| 84 | + |
| 85 | +- **_Issues Without Pull Request_** |
| 86 | + - **Purpose**: This chapter lists issues that have been closed since the last release but are not linked to any pull requests. |
| 87 | + - **Importance**: Helps maintainers identify changes that might not have been properly reviewed or documented through PRs, ensuring the integrity of the release documentation. |
| 88 | + |
| 89 | +- **_Issues Without User-Defined Labels_** |
| 90 | + - **Purpose**: Displays issues lacking the labels defined in the `chapters` configuration. |
| 91 | + - **Importance**: Ensures all issues are categorized correctly according to the project's classification system. It aids in organizing release notes into predefined chapters effectively. |
| 92 | + |
| 93 | +- **_Issues Without Release Notes_** |
| 94 | + - **Purpose**: Identifies issues that do not contain a "Release Notes" comment. |
| 95 | + - **Importance**: Ensures that all significant changes are properly documented in the release notes, enhancing the completeness and usefulness of the release information provided to end-users. |
| 96 | + |
| 97 | +- **_PRs Without Linked Issue_** |
| 98 | + - **Purpose**: Lists pull requests that are not associated with any issues. |
| 99 | + - **Importance**: Encourages linking PRs to issues for better traceability and understanding of why changes were made. It also helps in maintaining a cohesive narrative in the project history and release notes. |
| 100 | + |
| 101 | +Each warning chapter acts as a quality check, ensuring that the release notes are comprehensive, well-organized, and meaningful. By addressing these warnings, project maintainers can significantly improve the clarity and effectiveness of their release documentation. |
| 102 | + |
| 103 | + |
| 104 | +### Contribution Guidelines |
| 105 | + |
| 106 | +We welcome contributions to the Generate Release Notes Action! Whether you're fixing bugs, improving documentation, or proposing new features, your help is appreciated. |
| 107 | + |
| 108 | +#### How to Contribute |
| 109 | +- **Submit Pull Requests**: Feel free to fork the repository, make changes, and submit a pull request. Please ensure your code adheres to the existing style and all tests pass. |
| 110 | +- **Report Issues**: If you encounter any bugs or issues, please report them via the repository's [Issues page](https://github.com/AbsaOSS/generate-release-notes/issues). |
| 111 | +- **Suggest Enhancements**: Have ideas on how to make this action better? Open an issue to suggest enhancements. |
| 112 | + |
| 113 | +Before contributing, please review our [contribution guidelines](https://github.com/AbsaOSS/generate-release-notes/blob/master/CONTRIBUTING.md) for more detailed information. |
| 114 | + |
| 115 | +### License Information |
| 116 | + |
| 117 | +This project is licensed under the Apache License 2.0. It is a liberal license that allows you great freedom in using, modifying, and distributing this software, while also providing an express grant of patent rights from contributors to users. |
| 118 | + |
| 119 | +For more details, see the [LICENSE](https://github.com/AbsaOSS/generate-release-notes/blob/master/LICENSE) file in the repository. |
| 120 | + |
| 121 | +### Contact or Support Information |
| 122 | + |
| 123 | +If you need help with using or contributing to Generate Release Notes Action, or if you have any questions or feedback, don't hesitate to reach out: |
| 124 | + |
| 125 | +- **Issue Tracker**: For technical issues or feature requests, use the [GitHub Issues page](https://github.com/AbsaOSS/generate-release-notes/issues). |
| 126 | +- **Discussion Forum**: For general questions and discussions, join our [GitHub Discussions forum](https://github.com/AbsaOSS/generate-release-notes/discussions). |
0 commit comments