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

45 changes: 45 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,45 @@
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:
APP_SECRET: ${{ secrets.LARK_APP_SECRET }}
APP_ID: ${{ secrets.LARK_APP_ID }}
REPOSITORY_NAME: Fullstack Template
RECEIVE_ID_TYPE: email
RECEIVE_ID: [email protected]
VERSION: ${{ github.ref_name }}
LINK: https://github.com/${{ github.repository }}/releases/tag/${{ github.ref_name }}
uses: docker://lesanpi/lark-release-version-card:v1.1
# with:
# args: 'comando1 arg1 comando2 arg2'

# runs-on: ubuntu-latest
# container:
# image: lesanpi/lark-release-version-card
# env:
# VERSION: ${{ github.ref_name }}
# LINK: https://github.com/${{ github.repository }}/releases/tag/${{ github.ref_name }}
# RECEIVE_ID_TYPE: 'email'
# RECEIVE_ID: '[email protected]'
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 and then attempts to use a Docker container for further actions. Here's a code review:

Strengths:

  • Clear Structure: The workflow is well-organized into jobs and steps.
  • Uses GITHUB_TOKEN: Properly uses the built-in GITHUB_TOKEN for authentication.
  • Tag Filtering: Only triggers on pushes with tags starting with v.
  • Release Creation: The gh release create command is concise and effective. The --generate-notes option is helpful.
  • Title Extraction: Cleverly extracts the version number from the tag using parameter expansion ${tag#v}.

Weaknesses and Potential Improvements:

  • Error Handling: The workflow lacks error handling. If gh release create or the Docker step fails, the workflow will stop without providing informative error messages. Consider adding if conditions to check the exit codes of commands.
  • Docker Image Dependency: The workflow depends on a custom Docker image, lesanpi/lark-release-version-card:v1.0. This introduces an external dependency that could break if the image is unavailable or updated incompatibly. Consider including a fallback mechanism or making the image more readily available (e.g., via a public registry).
  • Commented-Out Configuration: The commented-out section under the "New release" step suggests an alternative approach using a container. This is confusing. Either use one approach or the other, don't leave both commented out. Decide which method is better and remove the other. If using the Docker approach, uncomment and fill in the necessary values.
  • Docker Best Practices: If sticking with the Docker approach, using docker run directly within the workflow might be more robust than uses: docker://.... This would give more control over the container's environment and allow for better error handling. The commented-out section seems more complete than using uses: docker://.
  • Hardcoded Email: The commented-out RECEIVE_ID is hardcoded. It should be configurable via workflow inputs or secrets for better security and reusability.
  • Lack of description in New release step: There's no description of what this step is actually intended to do.

Bug Risks:

  • Image Availability: The main bug risk is the unavailability or incompatibility of the lesanpi/lark-release-version-card:v1.0 Docker image.
  • Command Failures: Failure of either the gh release create command or the Docker command without appropriate error handling.

Suggested Improvements:

  1. Add Error Handling: Wrap commands in if statements to check their exit codes and log errors.

  2. Choose a Docker approach (or remove it): Decide whether to use the commented-out Docker section or the uses: docker:// method. Remove the other. If using the docker run method, uncomment and fill in the missing parts.

  3. Refactor Docker Step (if using): Use docker run directly within the step if using the Docker container, this gives more control.

  4. Use Workflow Inputs or Secrets for Configuration: Move the email address (RECEIVE_ID) and other variables into workflow inputs or secrets to enhance security and reusability.

  5. Document the Docker Step: Clearly explain what this step does and why it's needed.

  6. Consider a more robust release generation method: Explore GitHub APIs for creating releases directly. While the gh CLI is convenient, a direct API call allows for even more control and error handling.

Example incorporating some improvements (using the Docker run approach and assuming the Docker image takes input parameters via environment variables):

name: Create release

on:
  push:
    tags:
      - 'v*'

permissions:
  contents: write

jobs:
  release:
    name: Release pushed tag
    runs-on: ubuntu-22.04
    env:
      RECEIVE_ID: ${{ secrets.RECEIVE_ID }} # Move email to secrets
    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
          if [ $? -ne 0 ]; then
            echo "Error creating release!"
            exit 1
          fi
      - name: Create Version Card (Docker)
        run: |
          docker run --rm \
            -e VERSION="${{ github.ref_name }}" \
            -e LINK="https://github.com/${{ github.repository }}/releases/tag/${{ github.ref_name }}" \
            -e RECEIVE_ID_TYPE="email" \
            -e RECEIVE_ID="${RECEIVE_ID}" \
            lesanpi/lark-release-version-card:v1.0
          if [ $? -ne 0 ]; then
            echo "Error creating version card!"
            exit 1
          fi

Remember to replace placeholders like secrets.RECEIVE_ID with actual secret values in your GitHub repository settings. This revised example provides better error handling and improved security. Remember to adapt it to the specific requirements and functionality of your lesanpi/lark-release-version-card Docker image.

Copy link

Choose a reason for hiding this comment

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

The gh release create command uses ${tag#v} to remove the leading 'v' from the tag name in the release title. Consider adding error handling around this command in case gh exits with a non-zero status. The current implementation silently fails if the release creation fails.

The Docker image lesanpi/lark-release-version-card:v1.0 is used. Ensure this image is publicly available and appropriately versioned. Consider adding a checksum verification step to improve security. Also, the commented-out section suggests an alternative approach; choose one and remove the other for clarity.

Using environment variables for sensitive information like APP_SECRET and APP_ID is good practice. However, consider using GitHub Actions secrets for all sensitive information, not just for GITHUB_TOKEN, for consistency. The commented-out section uses a different way to pass the environment variables to the docker container, choose one method.

The RECEIVE_ID is hardcoded. Consider making it configurable, perhaps via a workflow input or environment variable. This improves flexibility and allows use for different recipients.

The workflow only triggers on pushes with tags starting with 'v'. Consider adding a mechanism to handle potential errors during the release creation process, such as providing feedback to the user or retrying the process.

The use of github.ref_name directly as the VERSION might not be ideal for semantic versioning. Consider extracting the semantic version (e.g., using a regular expression) to ensure compatibility with version comparison tools. Also ensure github.ref_name always follows a semantic version pattern (otherwise the title of release could be wrongly created).

Copy link

Choose a reason for hiding this comment

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

The gh release create command uses --generate-notes. Consider adding a --prerelease flag if these are pre-releases to manage them separately on GitHub. This is important for versioning and release management practices.

The Lark notification section uses a Docker image. This introduces an external dependency and potential security risks if the image isn't properly vetted. Consider specifying the image digest for better security and reproducibility. The commented-out sections suggest alternative approaches; clarify which method is preferred and why the other was discarded. If the Docker approach is chosen, thoroughly document the image and its dependencies.

Error handling is missing. The script should include mechanisms to handle potential failures in gh release create and the Lark notification. Consider adding try...catch blocks or checking exit codes to provide informative error messages and prevent silent failures.

The hardcoded recipient email ([email protected]) should be parameterized or made configurable, perhaps via environment variables, to improve maintainability and adaptability.

The permissions: contents: write might be too broad. Consider restricting permissions to only what's needed for the release creation process, minimizing potential security risks. Review the GitHub Actions permissions documentation for more granular control.

The # with: section in the Lark notification step is commented out. If this was intended for future functionality, update the comment to reflect this intention and add a task to implement this. If it's no longer needed, remove it.

Consider adding logging statements throughout the workflow to aid in debugging and monitoring. This will help significantly during troubleshooting.

Copy link

Choose a reason for hiding this comment

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

  • The gh release create command uses parameter expansion ${tag#v} to remove the leading 'v' from the tag name in the title. This is fragile; it assumes all tags begin with 'v'. Consider a more robust method to handle tag naming variations or allow for configuration.

  • The Lark notification section uses a Docker image. This introduces a dependency on external resources which might impact reliability and build times. Consider using a native action for better maintainability and predictability. Also, the use of a docker image with a version of v1.0 is concerning, it should be pinned to a specific commit or tag and not a floating version to ensure stability and reproducibility.

  • The commented-out sections (# with, # runs-on, # container) are unnecessary and should be removed for clarity. Choose one approach (either uses with a docker image or a native action) and stick with it.

  • Hardcoding REPOSITORY_NAME, RECEIVE_ID_TYPE, and RECEIVE_ID directly in the workflow is not ideal. These values should be configurable through inputs or environment variables for better reusability and maintainability.

  • Error handling is missing. The workflow should include mechanisms to handle potential failures in gh release create and the Lark notification. Consider using if conditions or error checking to gracefully handle unexpected situations and prevent the workflow from silently failing.

  • The GITHUB_TOKEN is used with broad permissions (permissions: contents: write). This is a security risk. Consider using a more restrictive token with only the necessary permissions for creating the release. Explore using a personal access token (PAT) with fine-grained control for enhanced security.

Copy link

Choose a reason for hiding this comment

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

  • The gh release create command uses parameter expansion ${tag#v} to remove the leading 'v' from the tag name in the title. This is fragile; what if a tag doesn't start with 'v'? Consider a more robust method, perhaps a regular expression to extract the version number, handling various potential tag formats.

  • The Lark notification section uses a Docker image. This introduces a dependency outside of GitHub Actions' standard environment. Consider the maintainability and security implications of using a third-party Docker image. Provide a link to the Docker image's repository for review. Also, ensure that the Docker image is properly versioned and pinned to avoid unexpected updates breaking the workflow.

  • The commented-out section suggests an alternative approach using a container. The commented-out code should be removed for clarity. If this alternative is being considered, it should be fully fleshed out and tested before the current implementation is used.

  • The hardcoded values for REPOSITORY_NAME, RECEIVE_ID_TYPE, and RECEIVE_ID should be configurable via inputs or environment variables for reusability and flexibility across different repositories and users.

  • Error handling is missing. The script should gracefully handle potential failures, such as network issues or API errors from gh or the Lark notification service, logging errors and potentially failing the workflow.

  • Consider adding more informative logging throughout the workflow for better debugging and monitoring.

  • The permissions: contents: write statement grants broad permissions. Restrict this to only the necessary permissions if possible. For example, if only release creation is needed, specify the more granular permission.

Copy link

Choose a reason for hiding this comment

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

The gh release create command uses --generate-notes. Consider if this is always desired; manually crafted release notes might be preferable for certain releases. Provide a mechanism (e.g., configuration option) to control this.

The email notification step uses a Docker image (lesanpi/email-deploy:v1.0.0). This introduces a dependency on an external, potentially unstable, image. Consider using a more robust and established solution for email notifications, or at least adding detailed dependency management (e.g., specifying a specific commit SHA of the docker image rather than a tag) and thoroughly testing the email functionality.

The commented-out section suggests an alternative notification method. Either remove the commented-out code or decide which approach is preferred and implement it consistently. Avoid leaving commented-out code which will never be used as this creates clutter and makes the workflow harder to understand.

Error handling is missing. What happens if gh release create fails? The workflow should include checks for exit codes and appropriate handling of failures (e.g., logging, notifications, setting a workflow failure status).

The hardcoded RECEIVE_EMAIL address in the email notification step should be parameterized or fetched from secrets, not directly included. This is crucial for security best practices.

The APP_NAME variable is currently unused. Remove it unless it is intended for future use or it's used within the email-deploy image.

Consider adding more descriptive names to the steps for better readability and maintainability (e.g., Create GitHub Release, Send Release Notification).

The workflow is tightly coupled to a specific email address. Consider adding flexibility to support multiple recipients or different notification methods.

Copy link

Choose a reason for hiding this comment

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

  • The gh release create command uses parameter expansion ${tag#v} to remove the leading 'v' from the tag name in the title. This is fragile; if the tag doesn't start with 'v', the title will be incorrect. Consider a more robust approach, perhaps using a regular expression or string manipulation to extract the version number regardless of prefix.

  • Hardcoding RECEIVE_EMAIL is not ideal. Consider making this configurable via environment variables or inputs.

  • The commented-out section suggests a previous attempt using a different notification method. Remove the commented-out code entirely for clarity. The current implementation using a Docker image is preferable, provided the image is well-maintained and secure.

  • The Docker image lesanpi/email-deploy:v1.0.0 should be thoroughly vetted for security vulnerabilities before deploying to production. Consider using a trusted registry and regularly checking for updates. Including a specific SHA or digest instead of just the tag would further enhance security.

  • Error handling is missing. The script should gracefully handle potential failures in gh release create and the email sending process. Add appropriate error checks and logging.

  • The workflow uses GITHUB_TOKEN which has limited permissions. While it works for creating releases, ensure this is sufficient for all future needs. Consider using a personal access token with more granular permissions if required by future extensions.

  • Consider adding a step to validate the tag format before proceeding to create the release. This will prevent unexpected behavior with malformed tags.

  • Document the purpose and expected behavior of the lesanpi/email-deploy:v1.0.0 Docker image within the workflow file. A link to its documentation would be beneficial.

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

This file was deleted.