Skip to content
Advent of Open Source

Day 12: The Nexus of Continuity

The Constellation Archives

On this twelfth day, the Keeper leads you to the Constellation Archives, a celestial observatory where the milestones of countless creations are immortalized as shimmering stars in the vast tapestry of the cosmos. Overseeing this sacred domain is the Chronicler of Continuity, a diligent caretaker who ensures that each star shines with purpose, forming a map that others can follow.

The Chronicler speaks of the Chaos of Inconsistency, a force that disrupts and obscures the brilliance of these celestial markers, turning them into faint, fractured lights. To guard against this, the stars must be crafted with care, their stories clear and enduring, so they may guide those who look to the heavens for direction.

Choose the rune that best suits your skills and experience:

If you’re joining the village today, you can always catch up on the instructions from Day 1 to get up to speed.

Beginner: Create Your First Release

Snowflake rune
Beginner level for folks starting a new artifact

The Chronicler of Continuity approaches, carrying an artifact that gleams with quiet authority—the Compass of Continuity. They hand it to you, its surface shimmering faintly as it aligns to your presence.

This compass is not for navigation alone,

the Chronicler explains, their voice calm yet resolute.

It reveals where the light of your work can shine brightest. Use it to create a marker that speaks not just of where you are but of where your craft is destined to go. Each step forward becomes clearer when the past is well lit.

You grip the compass, feeling its warmth, and turn toward the starry expanse.

Releasing a first version is a crucial milestone in the lifecycle of any Open Source project. It signals that your project is ready to be used, evaluated, or contributed to by the community. A properly managed release process brings clarity to your project’s development progress, provides users with a snapshot of its current state, and establishes a clear foundation for future updates. Whether you’re building a tool, library, or platform, crafting a release helps others engage with your work confidently.

Today’s challenge focuses on guiding you through the steps of creating your first release. You’ll learn how to properly version your project, communicate changes with a changelog, and share your work with the world. Completing this challenge will not only boost the visibility of your project but also lay the groundwork for future enhancements and contributions.

  1. Understand semantic versioning.

    Semantic Versioning (SemVer) is a widely adopted standard for versioning software that makes it easier to understand the scope of changes between releases. Visit the Semantic Versioning website for detailed information.

    In short:

    • MAJOR: Increment this number for incompatible, breaking changes.
    • MINOR: Increment this number for backward-compatible feature additions.
    • PATCH: Increment this number for backward-compatible bug fixes.

    For your first release, start with version v0.1.0. This indicates that your project is still under development and may evolve significantly in the future.

  2. Set up the version.

    Update or create the version information in your project files. For example:

    • In an npm project, edit the package.json file:

      {
        "name": "my-project",
        "version": "0.1.0",
        "description": "My awesome project",
        ...
      }

    • For other ecosystems, check your package manager’s documentation (e.g., Python’s setup.py, Ruby’s gemspec, etc.).

    • For applications, you can include the version in the footer or about page.

    Ensure this version is reflected wherever your project specifies its versioning information.

  3. Create a changelog.

    A changelog helps users understand what’s the differences between versions. Create a CHANGELOG.md file in your repository.

    Here’s an example for your first release:

    CHANGELOG.md
    # Changelog
    

    ## v0.1.0
    

    This is the first release of the project.
    

    {/* insert your project's description here> */}
    

    ### Features
    

    - {/* insert your first feature here */}
    

    ### Docs
    - Added README file with basic project information
    

    ### Chore
    

    - Set up CI workflow
      - Spell check
      - Linting
      - Basic tests

    Commit and push this file to your repository.

  4. Tag the release.

    Tags mark specific points in your project’s history. Use Git to tag your release:

    Terminal window
    git tag -a v0.1.0 -m "chore(release): v0.1.0"
    git push origin v0.1.0

    This creates and pushes a tag named v0.1.0 to your remote repository. Tags are displayed in the “Releases” section of your project on GitHub.

  5. Create the release on GitHub.

    Release notes are a way to communicate what’s new in your release. They help users understand what has changed and what they need to do to upgrade.

    You can write release notes in a Markdown file or directly in the GitHub release interface.

    Use the GitHub interface to create your release.

    1. Navigate to the “Releases” section of your repository and click on the Create a new release button.

    2. Click on Choose a tag, and select the tag you’ve just created (e.g., v0.1.0).

    3. Let the previous tag as auto.

    4. Enter a title for your release (e.g., “v0.1.0”).

    5. Add a description of your release.

      Copy the relevant section from your changelog to communicate changes effectively., or adapt it to make it more user-friendly.

    6. Click on the Publish release button.

    7. Go back to your repository main page, and you’ll see the release you’ve just created.

  6. (Optional) Publish your project.

    If your project is a library or tool that others will install, you can publish it to a package manager, you can publish it now.

    For npm, run:

    Terminal window
    npm pack
    npm publish

    This command will make your package available on the npm registry for others to install. For other ecosystems, refer to the relevant publishing instructions (e.g., PyPI for Python).

Congratulations on completing your first release! This milestone not only formalizes your project’s progress but also makes it easier for others to explore, use, and contribute to your work. By adopting Semantic Versioning, creating a clear changelog, and leveraging GitHub’s release tools, you’ve set a solid foundation for future growth.

Take a moment to celebrate your achievement, and don’t forget: regular releases and clear communication will make your project even more valuable to the community. Well done!

Success Criteria

  • ✓ Semantic Versioning (v0.1.0) is implemented.
  • ✓ A CHANGELOG.md file is created and committed to the repository.
  • ✓ A tagged release (v0.1.0) is pushed to the remote repository.
  • ✓ A release with clear notes is published on GitHub.
  • ✓ (Optional) The project is published to a package manager (e.g., npm, PyPI).

You return to the Chronicler, the Compass of Continuity aglow in your hand, its light pulsing gently in harmony with your thoughts. The Chronicler examines your work, a faint smile gracing their features.

You have set your first marker in the tapestry of the cosmos,

they say, their tone both encouraging and reflective.

This star will guide others and remind you of the foundation you’ve built. Remember, the compass will always point you toward clarity—use it well as you continue to chart your journey.

You glance back at the shining constellation, the new star bright and steady, before stepping forward. With the Compass of Continuity in hand, the path ahead feels more certain, illuminated by purpose.

The Chronicler’s Guidance

In the Constellation Archives, every star has a story, a snapshot of your artifact’s evolution. Through structured and consistent release management, you not only preserve your artifact’s history but also guide its future. Remember: clarity is the cornerstone of continuity.

Record your progress, traveller, and prepare for the next stage of your journey. The Advent of Open Source continues, with new challenges on the horizon.

Intermediate: Automate Release Management

Snowball rune
Intermediate level for folks wanting to enhance an existing artifact

The Chronicler of Continuity stands before you once more, the Compass of Continuity resting in their hands. They hold it out, and as your fingers brush its surface, the compass begins to hum softly, its needle circling before settling into place.

The stars of the Constellation Archives shine brightest when they align with precision,

the Chronicler begins, their gaze steady.

But precision does not come from effort alone. It is the rhythm of harmony—each step, each motion working together, uninterrupted. The compass now holds the key to such harmony, unlocking a way to let the stars align on their own, freeing your focus for the greater expanse ahead.

With a measured gesture, the Chronicler turns toward the observatory’s intricate machinery, its mechanisms clicking in perfect time.

Let the compass guide you to orchestrate these movements, ensuring that no star falls out of place and no light is left to fade.

The compass glows warmly in your hands, its faint vibrations a promise of what can be achieved.

Managing releases manually can become a tedious and error-prone process, especially as your project grows and gains contributors. Automating release management allows you to streamline versioning, changelog generation, and deployment, ensuring that each release is consistent, traceable, and transparent. This saves time, minimizes mistakes, and boosts collaboration, enabling contributors to focus on development rather than administrative tasks.

Today’s challenge focuses on automating your release management process by implementing automated versioning, generating changelogs, and deploying releases to production with a CI/CD pipeline. You will implement a system that handles versioning, creates changelogs automatically, and deploys new versions effortlessly, providing a more professional and scalable release process for your Open Source project.

  1. Implement semantic versioning.

    This is probably already done but if not, ensure your project follows Semantic Versioning (SemVer) guidelines as it is the most widely adopted standard for versioning software.

    Increment the version number based on the type of changes made in each release:

    • MAJOR: Increment this number for incompatible, breaking changes.
    • MINOR: Increment this number for backward-compatible feature additions.
    • PATCH: Increment this number for backward-compatible bug fixes.

    Using semantic versioning allows contributors to understand the scope of changes just by looking at the version number. By automating the versioning process, you can avoid human error and ensure consistency.

  2. Configure automated versioning.

    Consider using Conventional Commits for your commit messages, and tools like semantic-release or Changesets to automatically manage versioning. Both tools allow you to automatically manage versioning. Both tools allow you to automatically update version numbers based on the type of changes made in your project.

    • semantic-release analyzes the commit history and commit messages using Conventional Commits specification to determine the appropriate version bump (major, minor, patch).
    • Changesets is another powerful tool for managing versions, especially in monorepos or multi-package projects. It works by creating “changeset” files that describe the changes between releases, and then it automates version bumping and changelog generation.

    Choose the tool that best fits your project’s needs and set it up to automate versioning.

  3. Automate changelog generation.

    Automatic changelog generation is a vital part of the release process. With tools like Changesets, Standard version, conventional-changelog-cli, or built-in features from semantic-release, you can automatically generate a changelog that lists all changes made in each release, ensuring transparency and reducing manual effort.

    By using these tools, you can eliminate the need for manual changelog updates and ensure that your changelog is always in sync with your releases.

  4. Create release workflow in CI/CD pipeline.

    To complete the automation process, set up a CI/CD pipeline to deploy your releases to the production environment. This ensures that every new version is automatically deployed, reducing manual intervention and providing a smooth release process.

    1. Use CI/CD tools like GitHub Actions, Travis CI, CircleCI, or GitLab CI/CD to create workflows that automatically trigger after a version update.

    2. Set up a release workflow that:

      • Runs tests to verify the release is stable.
      • Deploys the release to a staging or production environment.
      • Tags the release and pushes the changelog.
      • If applicable, publishes the release to a package manager, and to the GitHub release page by creating a new release.

    This automated process will give your project a professional edge, as every release is tested and deployed automatically without manual intervention.

  5. Document your versioning policy.

    It’s essential to communicate our versioning policy clearly to contributors and users. Document your versioning strategy, including how version numbers are incremented, the rules for commit messages, and how changelogs are generated into your contributing guidelines. This will help maintain consistency as your project grows and more contributors get involved.

Automating release management not only saves time and reduces human error but also enhances the professionalism and reliability of your project. By implementing automated versioning, changelog generation, and CI/CD pipelines, you’re making your project easier to maintain and scale. This process ensures that every release is consistent, transparent, and easy to track, helping you and your contributors focus on what really matters—building great features and improving the project.

Congratulations on completing this challenge! By automating your release management, you’re streamlining your development process and setting your project up for success.

Success Criteria

  • ✓ Implemented Conventional Commits for commit messages.
  • ✓ Implemented semantic versioning.
  • ✓ Explored and optionally set up a versioning automation tool (e.g., semantic-release, Changesets).
  • ✓ Explored and optionally set up a changelog automation tool (e.g., Changesets, Standard version).
  • ✓ Created a release workflow in a CI/CD pipeline.
  • ✓ Documented your versioning policy in your contributing guidelines.

The Chronicler watches as you return, the Compass of Continuity now pulsing with a steady, radiant light.

You have brought rhythm to the stars,

they say, nodding in approval as they examine the changes you’ve wrought in the observatory.

The Chaos of Inconsistency can no longer breach these walls. You have created a cadence that ensures each star will shine, not through force of will, but through the harmony you’ve woven into the cosmos.

The observatory’s mechanisms begin to move with new energy, their sounds now a melody rather than a mere series of clicks. The Chronicler places a hand on your shoulder, their tone both solemn and proud.

This is a gift not just to the Archives but to all who look to its light. Continue your journey, and let the compass remind you that every great creation thrives on the balance of consistency and care.

You leave the Constellation Archives, the Compass of Continuity still warm in your grip, its glow lighting the path ahead.

The Chronicler’s Guidance

In the Constellation Archives, every star has a story, a snapshot of your artifact’s evolution. Through structured and consistent release management, you not only preserve your artifact’s history but also guide its future. Remember: clarity is the cornerstone of continuity.

Record your progress, traveller, and prepare for the next stage of your journey. The Advent of Open Source continues, with new challenges on the horizon.

Advanced: Streamline Multi-Repository Release Workflows

Ice rune
Advanced level for folks wanting to enhance an existing large artifact or several org/personal artifacts

The Chronicler of Continuity greets you at the threshold of a vast, starry chamber unlike any you’ve seen before. The Constellation Archives have expanded, their celestial light now revealing countless clusters of stars, each representing a different thread in the tapestry of creation. The Chronicler gestures toward the array.

Behold the Web of Realms, where each cluster is a craft of its own,

they explain, their voice reverent.

Each shines brightly, yet their light must weave together to form a constellation that truly guides those who gaze upon it.

The Compass of Continuity hums in your hands, its needle vibrating as if eager to align with the scattered lights above. The Chronicler regards you with quiet determination.

To master this web is no small feat. Each thread must move in unison, their rhythms synchronized without falter. Trust in the compass, for it will reveal the patterns hidden within the chaos. Follow them, and bring harmony to the many realms before you.

You turn to the web of lights, its beauty matched only by the challenge it presents.

As your Open Source efforts expand, managing and releasing multiple repositories efficiently becomes critical. This is particularly true for projects that involve monorepos or interconnected repositories that need to work together. Streamlining your workflows to handle simultaneous releases, synchronized dependencies, and consistent communication can save time, reduce errors, and improve the contributor experience.

Today’s challenge focuses on refining your release workflows for multiple repositories. You will start by enabling simultaneous releases for monorepos or related repositories, then automate dependency updates, generate cross-repository release summaries, and maintain a central changelog. These steps will help you scale your project management while maintaining high-quality standards.

  1. Enable simultaneous releases.

    Coordinating releases across interconnected repositories or packages can be challenging. By adopting tools and workflows designed for simultaneous releases, you can ensure all related repositories are updated in sync, reducing the risk of incompatibility or confusion.

    1. Monorepo scenario.

      • Use a tool like Lerna or Changesets to manage and release multiple packages within a monorepo.

      • Configure versioning and publishing workflows:

        • Use Lerna to manage versioning and publishing for each package.
        • Use Changesets to manage versioning and changelogs for each package.

      • These tools automate version updates, changelog generation, and publishing to package registries like npm.

    2. Multi-repository scenario.

      Use CI/CD pipelines to trigger releases across repositories:

      • For example, create a “meta repository” with a workflow that triggers coordinated releases in sibling repositories using GitHub Actions or similar tools.
      • Use scripts and tools like nx or custom orchestration scripts to ensure smooth cross-repository coordination.

    3. Document the workflow.

      As usual in the challenges of this level, documentation is key. Clearly define and document the release process to ensure all the core team follows the same standards.

  2. Automate dependency updates between repositories.

    Once simultaneous releases are in place, it’s essential to ensure that dependencies between repositories are updated automatically. This avoids manual synchronization efforts and ensures compatibility across repositories.

    1. Configure dependency management.

      You already have in place tools like Dependabot or Renovate to monitor and update dependencies at a dedicated time each week for external dependencies.

      Ensure these tools are also triggered by the release of a new version of a dependency in a related repository.

    2. Centralize dependency policies.

      If not already in place, create shared policies or configuration files to define update frequencies, testing strategies, and version ranges.

      The description must take into account the external dependencies and the internal dependencies between the repositories.

    3. Test updates automatically.

      Use CI pipelines to validate dependency updates before merging.

  3. Generate cross-repository release summaries.

    Informing contributors and users about changes across repositories can improve collaboration and transparency. Automating cross-repository release summaries ensures everyone stays updated.

    They need to know what dependencies have been updated, which ones depend on them, and what changes have been made in each repository so they can adapt their code accordingly.

    1. Set up release summary workflows.

      Use GitHub Actions or other CI/CD tools to aggregate release notes across repositories. Tools like Release Drafter or custom scripts can pull changelog data and generate a summary.

    2. Custom aggregation scripts.

      Use GitHub’s API via tools like Octokit to pull release notes or commit messages and combine them into a central summary.

  4. Maintain a central changelog.

    One possibility could be to have a central changelog that provides an overarching view of changes across all repositories. This can be especially useful for users and contributors who need to keep track of updates without navigating individual repositories.

    1. Create a central changelog repository.

      Use a dedicated repository for documentation, including a CHANGELOG.md summarizing updates from all related repositories.

    2. Automate changelog updates.

      Extend your workflows to automatically append changes from individual repositories to the central changelog. Tools like Changesets or custom scripts can assist here.

    3. Organize for clarity.

      Use structured headings and include links to the detailed release notes of individual repositories.

      CHANGELOG.md
      ## Multi-Repository Project - Release Summary (v2.3.0)
      

      ### Repository A
      - Added feature X ([#456](https://github.com/org/repo-a/pull/456))
      - Fixed bug Y ([#457](https://github.com/org/repo-a/pull/457))
      

      ### Repository B
      - Updated dependency Z to v3.0.0
      - Improved CI workflows

Streamlining multi-repository release workflows not only improves efficiency but also reduces errors and enhances collaboration across repositories. By enabling simultaneous releases, synchronizing dependencies, generating cross-repository summaries, and maintaining a central changelog, you’ve taken an important step toward professionalizing your project management.

Congratulations on completing this challenge! Your project is now easier to maintain, more transparent, and better equipped to scale. Keep iterating as your repositories and contributors grow.

Success Criteria

  • ✓ Simultaneous release processes are established for all relevant repositories or packages.
  • ✓ Dependency updates are automated between repositories.
  • ✓ Cross-repository release summaries are generated and shared.
  • ✓ (Optional) A central changelog is maintained and updated automatically with changes from all repositories.
  • ✓ Documentation for all workflows is provided to ensure long-term consistency.

As you return, the Chronicler observes the glow of the Compass of Continuity, now brighter and steadier than ever. Behind you, the once-fragmented clusters in the Web of Realms now pulse in unison, their light flowing together like the notes of a symphony.

You have woven the threads,

the Chronicler says, their voice filled with awe.

What was once a scattering of lights now forms a constellation of purpose. Each cluster moves with the others, their harmony a guide for all who follow.

The celestial mechanisms within the chamber adjust, their gears aligning seamlessly to this newfound rhythm. The Chronicler turns to you, their expression both proud and contemplative.

Remember this moment. A web in balance can be a beacon, but its strength depends on constant care. Tend to it, nurture its patterns, and let its light guide others long after the stars have shifted.

The Chronicler bows deeply as you take your leave, the Compass of Continuity now a trusted ally in your journey, its glow illuminating the path to new challenges ahead.

The Chronicler’s Guidance

In the Constellation Archives, every star has a story, a snapshot of your artifact’s evolution. Through structured and consistent release management, you not only preserve your artifact’s history but also guide its future. Remember: clarity is the cornerstone of continuity.

Record your progress, traveller, and prepare for the next stage of your journey. The Advent of Open Source continues, with new challenges on the horizon.