Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: Release note #31

Open
wants to merge 18 commits into
base: main
Choose a base branch
from
Open

feat: Release note #31

Show file tree
Hide file tree
Changes from 16 commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
67b3f07
feat: release note
lesanpi Jan 2, 2025
b504ec3
feat: use labels for each pull request
lesanpi Jan 2, 2025
ccc0400
fix: release titles
lesanpi Jan 2, 2025
5092fe6
feat: changelog title
lesanpi Jan 2, 2025
5696d62
feat: new labels
lesanpi Jan 2, 2025
d016b62
feat: notification release
lesanpi Jan 2, 2025
319317d
feat: notification release
lesanpi Jan 2, 2025
adde2cb
feat: release note
lesanpi Jan 2, 2025
db86a28
build: pipeline secrets
lesanpi Jan 3, 2025
2aa57d5
chore: title step for release notification
lesanpi Jan 3, 2025
5dbc6a3
feat: repository name
lesanpi Jan 3, 2025
5edf0bf
chore: use v1.1 notification image
lesanpi Jan 3, 2025
ef62226
feat: release note email notification
lesanpi Jan 3, 2025
12678d6
chore: postmark secret token
lesanpi Jan 3, 2025
15ddd01
chore: remove comments
lesanpi Jan 3, 2025
c6aba60
feat: release notification email
lesanpi Jan 13, 2025
23f92bc
chore: bump noti version
lesanpi Jan 13, 2025
3dbc058
chore: change noti email
lesanpi Jan 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions .github/release.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
changelog:
exclude:
labels:
- ignore-for-release
categories:
- title: Breaking Changes 🛠
labels:
- breaking-change
- title: New Features 🎉
labels:
- enhancement
- feat
- kind:feat
- feature
- title: Bug fixes 🐛
labels:
- fix
- kind:fix
- title: Documentation 📄
labels:
- documentation
- title: Other Changes
labels:
- '*'
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This code patch adds a changelog configuration, likely for a tool that automatically generates changelogs based on Git commits and issue labels. The configuration is well-structured and uses clear category titles and label selectors.

Potential Bug Risks & Improvements:

  • Label Overlap: The biggest risk is unintentional overlap between label categories. For example, a commit could have both enhancement and breaking-change labels. The configuration doesn't define precedence; the commit might appear in multiple sections. Consider adding a mechanism to handle conflicting labels, perhaps prioritizing breaking-change over others. This might involve a custom sorting or filtering step in the changelog generation process.

  • Wildcard Handling (*): The Other Changes category uses a wildcard (*). While convenient, this is a potential catch-all that could obscure important changes not covered by other categories. It's best practice to be explicit. Consider reviewing your label set to ensure all relevant labels are explicitly assigned to categories.

  • Missing kind Label Handling: The kind labels (kind:fix, kind:feat) are included but might not be sufficient if your team uses additional kind labels. It might be useful to either explicitly list all possible kind labels or consider a more flexible approach that handles unknown kind labels appropriately.

  • Label Case Sensitivity: The configuration doesn't specify whether label matching is case-sensitive. Ensure consistency across your team regarding label capitalization to prevent commits from being accidentally omitted from the changelog. Explicitly handle case-insensitivity in your changelog generation tool if it's not default behavior.

  • No Error Handling: The configuration doesn't define behavior when a commit doesn't have any of the specified labels. This might lead to commits being dropped entirely or falling into the wildcard category by default. Consider a default category or logging mechanism to handle uncategorized commits.

  • Missing Scope for Breaking Changes: Breaking changes should ideally include a concise scope describing what part of the system was affected. While not directly part of this configuration, encourage your team to use a consistent convention (e.g., BREAKING CHANGE: <Scope>: <Description>) in commit messages.

Improvement Suggestions:

  • Add comments: Add comments explaining the rationale behind each category and label selection. This will improve maintainability and understanding for others.

  • Consider a more structured format (e.g., YAML): While the current format is readable, a structured format like YAML would improve readability and make it easier to manage as the configuration grows. This would allow for easier validation and processing.

Overall, the patch is a good starting point, but requires further refinement to handle edge cases and ensure accuracy in changelog generation. Addressing the potential risks outlined above will improve the robustness and reliability of the changelog process.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This code patch adds a changelog configuration, likely for a tool like standard-version or a similar changelog generator. The configuration defines categories of changes based on GitHub issue/PR labels.

Here's a code review:

Strengths:

  • Clear Categorization: The categories are well-defined and use common label prefixes for different types of changes (breaking, features, bug fixes, documentation).
  • Comprehensive Label Coverage: The labels section within each category covers a variety of common label variations, improving robustness. The wildcard "*" in "Other Changes" is a good catch-all.
  • Readability: The YAML is well-formatted and easy to understand.

Potential Issues/Improvements:

  • Missing exclude examples: While the exclude section is present, it only shows excluding labels. It would be beneficial to also show examples of excluding entire categories or even specific PRs/issues by number or title (if the tool supports it). This would make the configuration more complete and illustrative.
  • Label Consistency: Consider standardizing label names for better consistency. For example, kind:feat and feat are essentially doing the same thing – perhaps choose one convention consistently. Similarly, consider consolidating enhancement and feature into one.
  • Error Handling: The configuration lacks error handling. What happens if a PR/issue has multiple conflicting labels (e.g., both breaking-change and fix)? The tool's default behavior in such cases should be documented or clarified. A more robust solution might be to define precedence rules for labels.
  • Tool Specificity: The code is only useful within the context of a specific changelog generation tool. It's important to clearly document which tool this configuration is for (e.g., in a comment or related documentation).

Bug Risks:

The primary risk is unexpected behavior due to label conflicts or edge cases not explicitly handled in the configuration. Testing with various label combinations is crucial.

Suggested Improvements:

  1. Add examples to exclude: Show how to exclude specific issues/PRs or categories.
  2. Consolidate labels: Reduce redundancy in label names (e.g., use only feat instead of feat, kind:feat, feature, enhancement).
  3. Document label conflict resolution: Clarify how the tool handles conflicts in labels. Consider adding a precedence order (e.g., breaking-change overrides fix).
  4. Add comments: Include a comment specifying the changelog generation tool this configuration is for.

In summary, the patch is a good start, but adding more robust error handling and clarifying ambiguous points will significantly improve its reliability and usability. Thorough testing is essential.

34 changes: 34 additions & 0 deletions .github/workflows/release.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
name: Create release

on:
push:
tags:
- 'v*'

permissions:
contents: write

jobs:
release:
name: Release pushed tag
runs-on: ubuntu-22.04
steps:
- name: Create release
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
tag: ${{ github.ref_name }}
run: |
gh release create "$tag" \
--repo="$GITHUB_REPOSITORY" \
--title="${tag#v}" \
--generate-notes
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This GitHub Actions workflow creates a GitHub release for each tag matching the v* pattern. Here's a code review:

Strengths:

  • Clear Purpose: The workflow's purpose is easily understandable.
  • Uses gh CLI: Utilizing the gh CLI is efficient for interacting with GitHub.
  • Environment Variables: Properly uses environment variables for security (GITHUB_TOKEN) and dynamic values (tag, GITHUB_REPOSITORY).
  • Generate Notes: Automatically generates release notes, saving manual effort.
  • Tag Filtering: tags: - 'v*' effectively limits releases to tags starting with 'v'.

Weaknesses and Improvement Suggestions:

  • Error Handling: The script lacks error handling. If gh release create fails (e.g., network issue, invalid tag), the workflow will fail silently or with a generic GitHub Actions error message. Adding a try...catch block (if the gh CLI supports it or using a more robust scripting language) or checking the exit code of the gh command would improve robustness. Example:
      - name: Create release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          tag: ${{ github.ref_name }}
        run: |
          release_result=$(gh release create "$tag" \
              --repo="$GITHUB_REPOSITORY" \
              --title="${tag#v}" \
              --generate-notes)
          if [ $? -ne 0 ]; then
            echo "Error creating release: $release_result"
            exit 1
          fi

  • Release Name: --title="${tag#v}" removes the leading 'v' from the tag to create the release title. While functional, consider whether this is always desirable. You might want more control over the release title, perhaps allowing for customization or using a more descriptive name based on the tag or other sources.

  • Pre-release handling: The script doesn't differentiate between pre-releases (e.g., v1.0.0-beta) and final releases. The --prerelease flag in gh release create could be used to manage this if needed.

  • More Detailed Logging: Add more logging statements to track progress and aid in debugging. For instance, log the command being executed and the $tag value.

Bug Risks:

  • $? check reliability: The proposed error handling relies on $?. While generally reliable, unexpected behavior could occur under unusual circumstances. A more robust approach might involve parsing the output of gh release create for error messages.

  • Tag Format Inconsistency: If tags are not consistently prefixed with 'v', the title generation might produce unexpected results.

Improved Workflow (incorporating suggestions):

name: Create release

on:
  push:
    tags:
      - 'v*'

permissions:
  contents: write

jobs:
  release:
    name: Release pushed tag
    runs-on: ubuntu-22.04
    steps:
      - name: Create release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          tag: ${{ github.ref_name }}
        run: |
          echo "Creating release for tag: $tag"
          release_result=$(gh release create "$tag" \
              --repo="$GITHUB_REPOSITORY" \
              --title="Release ${tag#v}" \
              --generate-notes)
          if [ $? -ne 0 ]; then
            echo "Error creating release: $release_result"
            exit 1
          fi
          echo "Release created successfully!"

This improved version includes better error handling and more informative logging. Remember to adjust the release title generation as needed to match your desired naming conventions. Consider adding pre-release handling if necessary.

- name: New release notification
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
POSTMARK_SERVER_TOKEN: ${{ secrets.POSTMARK_SERVER_TOKEN }}
APP_NAME: Fullstack Template
VERSION: ${{ github.ref_name }}
RECEIVE_EMAIL: [email protected]
REPOSITORY: https://github.com/${{ github.repository }}
LINK: https://github.com/${{ github.repository }}/releases/tag/${{ github.ref_name }}
uses: docker://lesanpi/email-deploy:v1.1.0
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

The GitHub Actions workflow uses a Docker image for sending email notifications (`docker://lesanpi/email-deploy:v1.1.0`).  This introduces several risks:

* **Security:**  Using a third-party Docker image from an untrusted source is a significant security vulnerability. The image could contain malicious code.  Consider building a custom action or using a verified image from a trusted registry.
* **Maintainability:**  Dependency on an external image makes the workflow less maintainable.  Updates to the external image may break your workflow.  A custom action would provide more control and predictability.
* **Performance:** Pulling the Docker image adds to the workflow execution time.

**Recommendation:**  Replace the Docker image approach with a built-in GitHub Actions solution or a self-contained action.  GitHub provides built-in email functionality, or consider a lightweight action that uses a robust email library within the workflow itself (without external image dependencies).

**Example (using GitHub's built-in functionality - might require configuring email settings):**

The `release` job could be extended to use the `GITHUB_TOKEN` with the GitHub API to create a release and send an email notification using GitHub's API rather than an external action. This would significantly improve security and reliability.


**Example (Illustrative - Adapt to your specific needs):**  This example showcases the basic structure; error handling and more robust email formatting should be added.

```yaml
jobs:
  release:
    # ... other steps ...
    - name: Send Release Notification (Illustrative - Requires Setup)
      uses: actions/github-script@v6
      with:
        github-token: ${{ secrets.GITHUB_TOKEN }}
        script: |
          const { owner, repo, ref } = context.repo
          const tag = ref.replace('refs/tags/', '')

          //Requires appropriate GitHub org/repo settings for notifications
          github.rest.repos.createRelease({
            owner,
            repo,
            tag_name: tag,
            name: tag.replace('v', ''),
            body: `New release ${tag} deployed.  See ${context.payload.repository.html_url}/releases/tag/${tag}`,
          })

Remember to configure appropriate GitHub settings for email notifications if using this approach. This eliminates the Docker image dependency, enhancing security and maintainability. For a more sophisticated email, consider using a dedicated email sending library within the workflow instead of relying on the GitHub API's limited email features.

1 change: 0 additions & 1 deletion CHANGELOG.md
View file
Open in desktop

This file was deleted.