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 6 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.

32 changes: 32 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,32 @@
name: Create release

on:
push:
tags:
- 'v*'

permissions:
contents: write

jobs:
release:
name: Release pushed tag
runs-on: ubuntu-22.04
env:
VERSION: ${{ github.ref_name }}
LINK: https://github.com/${{ github.repository }}/releases/tag/${{ github.ref_name }}
RECEIVE_ID_TYPE: 'email'
RECEIVE_ID: '[email protected]'
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
runs-on: ubuntu-22.04 # Or another suitable runner
container: lesanpi/lark-release-version-card
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 when a tag starting with 'v' is pushed. Here's a code review:

Bug Risks and Potential Improvements:

  1. GITHUB_TOKEN Scope: The GITHUB_TOKEN is used within the create release step. While this works for creating releases, it might have insufficient permissions for other actions you might add later (e.g., uploading assets). Consider creating a dedicated PAT (Personal Access Token) with more specific permissions and storing it as a secret. This is a better security practice than relying on the default GITHUB_TOKEN.

  2. tag Variable Redundancy: The tag variable is defined in both the jobs.release.env and the steps.create release.env. This is redundant. Just use the env variable at the job level.

  3. Hardcoded Email: The RECEIVE_ID and RECEIVE_ID_TYPE are hardcoded. This is not flexible. If you want to notify different people, you'll need to modify the workflow. Consider making these configurable via workflow inputs or environment variables. Furthermore, these variables aren't used anywhere in the provided workflow; remove them unless another step relies on them (this step should only create the release).

  4. Error Handling: The gh release create command lacks error handling. If the command fails (e.g., due to network issues or permissions problems), the workflow will stop without indicating the error. Add a check for the exit code of the command and handle errors gracefully (e.g., using || exit 1).

  5. tag#v for Title: The "${tag#v}" removes the leading 'v' from the tag name to use as the release title. This works but could be improved for robustness. What if a tag doesn't start with 'v'? Consider using a more robust method like a regular expression to extract the version number, or at least handle the case where there's no 'v' gracefully.

  6. Unclear Second Step: The second step (New release) uses a Docker container lesanpi/lark-release-version-card. This step's purpose is unclear from the provided code snippet. Is it updating a webpage or creating a release note? Its context and purpose need better explanation in a comment. It also runs on a separate ubuntu-22.04 runner, potentially adding overhead. Ensure it's truly necessary as a separate step.

Revised Workflow (incorporating some improvements):

name: Create release

on:
  push:
    tags:
      - 'v*'

permissions:
  contents: write

jobs:
  release:
    name: Release pushed tag
    runs-on: ubuntu-22.04
    env:
      VERSION: ${{ github.ref_name }}
      TAG: ${{ github.ref_name }} # Renamed for clarity
    steps:
      - name: Create release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Consider a dedicated PAT
        run: |
          gh release create "$TAG" \
              --repo="$GITHUB_REPOSITORY" \
              --title="${{ github.ref_name | replace: 'v', '' }}" \
              --generate-notes || exit 1 # Added error handling
      - name: Update Version Card (Explain Purpose Here!) # Added comment for clarity
        runs-on: ubuntu-22.04
        container: lesanpi/lark-release-version-card
        # Consider adding env variables or inputs here to pass data from the first step.

This revised version addresses some of the concerns. Remember to replace secrets.GITHUB_TOKEN with a dedicated PAT if you choose that route. Always thoroughly test your workflow after making changes.

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 when a tag matching v* is pushed. Here's a code review with bug risks and improvement suggestions:

Bug Risks and Potential Issues:

  • GITHUB_TOKEN Scope: The GITHUB_TOKEN has limited permissions. While it works for creating releases, more complex actions within the release creation process might fail due to insufficient permissions. If future steps require broader access (e.g., updating other files), a dedicated, more privileged PAT (Personal Access Token) should be used instead and stored as a secret. This is generally best practice for security.

  • Hardcoded Email: The RECEIVE_ID and RECEIVE_ID_TYPE are hardcoded. This makes the workflow inflexible. Consider passing these as inputs to the workflow or using environment variables to make it configurable.

  • Error Handling: The script lacks error handling. If gh release create fails (e.g., due to network issues or an existing release with the same tag), the workflow will silently fail. Adding error handling (e.g., using || exit 1) is crucial.

  • Tag Parsing: The --title="${tag#v}" removes the leading 'v' from the tag. This is okay for this simple use case, but it's fragile. A more robust approach might use a regular expression to extract the version number from a more complex tag format (e.g., v1.2.3-beta).

  • Container Dependency: The lesanpi/lark-release-version-card container is used in a step named "New release". This step's purpose is unclear from the provided context. The workflow should clearly document what this container does and why it's necessary. There's a risk of the container becoming unavailable or outdated.

Improvement Suggestions:

  • More Descriptive Step Names: Step names like "Create release" are too generic. More descriptive names would improve readability, such as "Create GitHub Release with Tag".

  • Use github.event.repository: Instead of ${{ github.repository }}, use ${{ github.event.repository }} for better clarity and accuracy as it directly accesses the repository from the event.

  • Workflow Inputs: Allow users to configure the email address and other parameters as workflow inputs. This makes the workflow more reusable and adaptable.

  • Conditional Logic: Consider adding conditional logic to check if a release with the same tag already exists before attempting to create a new one to avoid duplicate releases.

  • Logging: Add more logging statements to track the workflow's progress and help with debugging.

  • Separate Concerns: Consider breaking the workflow into smaller, more focused jobs. This would improve maintainability and readability.

Revised Workflow (incorporating some suggestions):

name: Create Release

on:
  push:
    tags:
      - 'v*'

permissions:
  contents: write

jobs:
  release:
    name: Create GitHub Release
    runs-on: ubuntu-22.04
    env:
      VERSION: ${{ github.ref_name }}
      LINK: https://github.com/${{ github.event.repository }}/releases/tag/${{ github.ref_name }}
    steps:
      - name: Create Release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          tag: ${{ github.ref_name }}
        run: |
          gh release create "$tag" \
              --repo="${{ github.event.repository }}" \
              --title="${{ github.ref_name#v }}" \
              --generate-notes || exit 1 # Add error handling
      - name: Update Version Card (Explain Purpose Here)
        uses: actions/checkout@v3 # Check out code if needed by container
        container: lesanpi/lark-release-version-card
        # Add environment variables or inputs for the container
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          VERSION: ${{ github.ref_name }}

Remember to replace the placeholder comment in the "Update Version Card" step with a clear explanation of its functionality. This revised workflow addresses some of the key risks and incorporates improvements for better readability and maintainability. However, a more complete solution might require a more sophisticated approach to error handling, tag parsing, and possibly the use of a more robust method for managing secrets.

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

This file was deleted.