DOCSEARCHbyAlgolia
Submit Docs

Nyx Semantic Release Automation

repository·main·Indexed 42 days ago

https://github.com/mooltiverse/nyx

A comprehensive semantic release automation tool for managing project versioning, changelogs, and releases based on commit history and SemVer principles. Available as a CLI, GitHub Action, Gradle plug-in, and embeddable libraries for Go and Java.

Tokens
76.4K
Snippets
192
Records
327
Agent score
54%

What's inside Nyx

  1. Introduction to Nyx release automation

    main

    Nyx is a tool designed to automate release management tasks. It helps manage the complexities that arise as teams and projects grow by automating processes such as:

    • Tracking released versions
    • Managing merge policies between branches
    • Fetching information from commit history
    • Enforcing consistent versioning policies
    • Assigning consistent release numbers
    • Generating artifacts like changelogs
    • Publishing released artifacts
    • Sending notifications upon new releases

    Nyx can be configured via detailed custom settings or by using predefined presets to create a streamlined release workflow.

  2. Available Nyx Go libraries

    main

    Nyx offers two primary Go libraries for developers:

    1. Nyx Main: Provides the complete Nyx implementation as an embeddable library.
    2. Semantic Version: A flexible implementation of the Semantic Versioning specification. It supports parsing, ordering, bumping, and manipulating versions and their identifiers.

  4. Use Schedule branches for time-based releases

    main

    Schedule branches are short-lived branches used to track features intended for specific release windows. They are deleted once the schedule is reached.

    Types of Schedules:

    • Periodic (Release Train): Fixed release dates (e.g., every month), variable scope. Names: 2020-01-01, schedule/2020/may.
    • Roadmap: Fixed scope, variable release dates. Use release branches for these.
    • Agile: Reflects organizational structure like sprints or epics. Names: sprint/423, epic/21, story/6354.

    Note: It is good practice to implement a code freeze period before the actual release to ensure stability.

    # Examples of schedule branch names
schedule/2020/may
sprint/423
epic/21

  5. Principles for effective build and automation with Nyx

    main

    To ensure a reliable release process, build scripts should adhere to three core principles:

    1. Consistency: Tasks should not repeat the same work. Dependencies should be modeled so that the output of a task remains the same given the same input. Avoid duplicating code in build scripts; instead, refactor task dependencies or use parameters.
    2. Portability: The build process must be executable across all platforms and environments used by the team (e.g., local developer machines and CI/CD runners) yielding the same idempotent outcomes.
    3. Efficiency: Use incremental builds and parallel execution to avoid consuming unnecessary resources and to shorten build times.

    Nyx supports these principles by splitting its internal workflow into two phases: inference (fetching and elaborating information like version numbers) and publication (issuing the actual release). This allows the version number to be known and consistent even if the final release task is skipped (e.g., on feature branches), enabling incremental builds to resume correctly.

  6. Commit message conventions in the 'extended' preset

    main

    The extended preset supports several commit message conventions. By default, conventionalCommits and gitmoji are enabled.

    Note on evaluation order: gitmoji is evaluated after conventionalCommits. A commit is only matched against gitmoji if it does not yield a positive match against conventionalCommits.

    Conventional Commits For Merge

    This convention is not compliant with the official Conventional Commits specification and is not officially supported. It is intended for parsing merge commits (such as squashed merges) where the message body contains the titles of multiple individual commits. Because it can match a single message multiple times, it can yield different bump identifiers.

    If you wish to use this convention while using the extended preset, you must explicitly enable it in your configuration or copy its attributes to a custom configuration.

  7. Use Release branches for preparing releases

    main

    Release branches are used to prepare a specific version for issuance. This includes packaging, final testing, and minor adjustments. They are typically created from the mainline once the product is ready to release.

    Critical Warning: To avoid regressions, do not commit bug fixes to the release branch without also merging them into the mainline (e.g., via git cherry-pick).

    Naming Conventions: Use the major/minor version number.

    • release-v1.2
    • release/v1.2
    • rel/v1.2
    # Examples of release branch names
release/v1.2
rel/v1.2

  8. Use Nyx state for automation and substitutions

    main

    The Nyx state can be leveraged in several ways to automate project updates:

    1. Gradle Integration: State attributes can be accessed directly from Gradle build scripts as extra project properties.
    2. Text Substitutions: You can use state attributes to replace text tokens in arbitrary files within your project (e.g., automatically updating a version attribute in platform-specific descriptors).
    3. Lightweight Summaries: If you only need a subset of information that is easily parseable, use the summary or summaryFile configuration options instead of the full state file.

  10. How Substitutions work in Nyx

    main

    Substitutions allow you to replace arbitrary text tokens in any text file with static or dynamic content. This is useful for synchronizing version numbers or other metadata across different files (e.g., updating a package.json version to match the version detected by Nyx).

    Each substitution rule consists of three main components:

    1. Files: A regular path or glob defining which files the replacement applies to.
    2. Match: A regular expression used to identify the token to be replaced.
    3. Replace: The content to insert, which can be a static string or a template using dynamic attributes from the Nyx State.

    Substitutions are executed during the Make command. You can define custom substitutions or use presets, such as the Extended preset which contains common technology-specific rules.

  11. How templates work in Nyx

    main

    Nyx uses Handlebars templates to make configurations dynamic or to parameterize text outputs (strings, messages, or files). The template engine is provided with the internal state as the template scope, meaning all available state attributes are accessible within your templates.

    Because Handlebars is compatible with Mustache, you can reuse existing Mustache templates.

    Tip: To troubleshoot or reference available variables, you can serialize the state to a file.

  12. Understand dynamic argument names in Nyx

    main

    Nyx uses dynamic argument names to allow configuration of arbitrary services. This is achieved using a <NAME> placeholder in the argument key.

    For example, the argument --services-<NAME>-type=<TYPE> allows you to define a type for a service instance named <NAME>.

    Example: To set the type GITHUB for a service instance configured under the name gh, use: --services-gh-type=GITHUB

    This notation tells Nyx to create a service configuration named gh internally. Because these names are dynamic, Nyx will not throw an error if you provide an argument that does not match a known service name.

    --services-gh-type=GITHUB