Skip to content
Advent of Open Source

Day 13: The Symphony of Collaboration

The Resonance of Unity

The Keeper of the Repos leads you into a radiant courtyard filled with intertwining melodies. Each sound rises and falls in perfect harmony, creating a living symphony that seems to resonate in your very core. This is the Harmonic Courtyard, a place where voices converge, each one contributing to a greater whole.

At the center of the courtyard stands the Maestro of Synergy, a poised figure whose every gesture guides the ebb and flow of collaboration. With each movement of their baton, the melodies align, their combined strength forming a powerful chorus.

Every harmony relies on balance,

the Maestro says, their voice calm but firm.

Yet discord lurks in the absence of structure. Without clear direction, even the strongest voices can falter, and the symphony risks collapse.

You watch as a shadow, faint but persistent, edges along the courtyard—the Discord of Miscommunication. Its presence seems to dampen the melodies, threatening to unravel the balance.

The Maestro looks to you, their eyes reflecting both hope and resolve.

To preserve harmony, you must bring clarity and order to the symphony. Only then will the voices rise as one, uniting in a melody that echoes across the ages.

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: Add a Markdown Issue Template

Snowflake rune
Beginner level for folks starting a new artifact

The Maestro of Synergy stands before you, holding a small, rolled parchment tied with a silver thread.

In every symphony, a score is needed to guide the players,

the Maestro begins, extending the parchment toward you.

Without it, even the most talented performers can lose their way. This,

they explain,

is the Scroll of Clarity, a simple yet powerful tool. With it, you can offer guidance to those who seek to join the harmony.

You unfurl the parchment, its surface marked with delicate symbols that hint at structure and purpose.

Begin with this first note,

the Maestro instructs, their voice steady.

Offer a foundation that others can follow. A symphony flourishes when every voice knows where to begin.

You clutch the scroll tightly, ready to set the stage for an harmony that others can easily join.

Yesterday, you hit a major milestone by releasing the alpha version of your project. This marks the point where your work is no longer just a solo effort; it becomes something you can share with others, inviting them to participate, test, and provide feedback. With community engagement comes an opportunity to refine and improve your project collaboratively.

Today’s challenge focuses on setting up an essential part of any Open Source project: issue templates. Issues are a critical tool for tracking bugs, discussing features, and organizing contributions. By providing contributors with clear and structured guidance, you can ensure better communication and faster resolution of problems. Let’s dive into how to create a simple bug report template to help your contributors help you!

  1. What are issues?

    Issues are a built-in feature of repositories, designed to track tasks, bugs, feature requests, or ideas. They serve as the central communication hub between maintainers and contributors, enabling collaboration around a shared backlog.

    They are a way to communicate with the maintainers of a project and other contributors. Issues can be opened by anyone with a GitHub account, and they can be assigned to people, labeled, and closed when the task is completed.

    Each issue consists of several key fields:

    • Title: A short summary of the issue
    • Description: A detailed explanation, often written in Markdown
    • Labels: Tags that categorize issues.
      • Default labels in a GitHub repository are bug , documentation , duplicate , enhancement , good first issue , help wanted , invalid , question , wontfix
    • Assignees: People responsible for addressing the issue
    • Projects and Milestones: Optional tools for organizing issues into larger plans.

    For someone creating an issue, they can only fill out the title and description fields. But you can guide them further by providing a template with specific fields to fill out.

    Today, your objective is to create a basic Markdown issue template for bug reports, guiding contributors to provide essential information to address the issue effectively.

    The community can do that by default in GitHub by clicking on the Issues tab in your repository and then clicking on the New issue button.

  2. Create a bug report template.

    Providing an issue template improves the clarity and completeness of bug reports. A well-defined bug report saves time, minimizes confusion, and helps maintainers address problems faster. Follow the steps below to create a Markdown-based template for bug reports.

    1. In your repository, create a new file named .github/ISSUE_TEMPLATE/bug_report.md. This file will contain the template for bug reports.

      You can use the GitHub web interface for this or create the file locally and push it to your repository.

      By using GitHub interface, you’ll see some information and guidance appear automatically to help you create a template. But let’s not use that for now, as it’s related to form-style templates. We’ll create a simple Markdown template.

    2. Define the template content.

      Copy the example below into your bug_report.md file, and customize it as needed. This template includes key fields that help contributors provide a detailed bug report:

      .github/ISSUE_TEMPLATE/bug_report.md
      ---
      name: Bug Report
      about: Create a report to help us improve Avalanche
      title: "[BUG] "
      labels: bug
      assignees: ""
      ---
      

      **Describe the bug**
      

      A clear and concise description of what the bug is.
      

      **To Reproduce**
      

      Steps to reproduce the behavior:
      

      1. Go to '...'
      2. Click on '...'
      3. Scroll down to '...'
      4. See error
      

      **Expected behavior**
      

      A clear and concise description of what you expected to happen.
      

      **Screenshots**
      

      If applicable, add screenshots to help explain your problem.
      

      **Environment:**
      

      - OS: [e.g. iOS]
      - Browser [e.g. chrome, safari]
      - Version [e.g. 22]
      

      **Additional context**
      

      Add any other context about the problem here.

    3. Commit and push the template.

      Commit your changes with the chore: create bug report template message, then push them to your repository.

    4. Test your template.

      Go to the “Issues” tab in your repository and click on the New issue button. You should see a difference in the interface: you now have a choice between creating a blank issue or using the template you just created.

      Let’s see how it looks like… click on Bug Report and you’ll see a pre-filled issue form with the template you created.

    5. Update the README.

      To guide contributors on how to report bugs, update your README.md with a link to create new issues using your template:

      README.md
      Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before participating in the community.
      

      ## Bugs and Feature Requests
      

      Have a bug or a feature request? Please first search for existing and closed issues. If your problem or idea is not addressed yet, [please open a new issue](https://github.com/Open-reSource/avalanche/issues/new/choose).
      

      ## License

By completing this challenge, you’ve set the foundation for effective collaboration with your contributors. Issue templates ensure that bug reports are clear, complete, and actionable, saving time for both you and your community.

Congratulations! This is a small yet impactful step in professionalizing your project and fostering a productive Open Source environment. Keep going—you’re building something great!

You can create additional templates for different types of issues, such as feature requests, documentation improvements, security issues, and performance issues. That’s up to you!

Success Criteria

  • ✓ A .github/ISSUE_TEMPLATE/bug_report.md file exists in your repository.
  • ✓ The new issue template appears in the “Issues” tab when creating a new issue.
  • ✓ Your README.md includes a link for contributors to create issues.

The Scroll of Clarity glows faintly in your hands as you return to the courtyard, where the Maestro of Synergy awaits. You present the scroll, now inscribed with purposeful marks, its once-blank surface transformed into a guide for the symphony.

You have laid the first notes,

the Maestro says, their voice warm with approval.

Each mark on the scroll is a step toward unity, ensuring every voice finds its place within the melody.

The shadow of the Discord of Miscommunication recedes slightly, its hold weakened by the structure you’ve brought. The melodies in the courtyard seem to grow stronger, resonating with a renewed clarity.

Remember,

the Maestro advises,

even the simplest guidance can transform chaos into harmony. Build upon this foundation, and the symphony will continue to thrive.

With the Scroll of Clarity in your care, you feel the strength of the melodies around you, ready to weave even more voices into the growing harmony.

The Maestro’s Wisdom

Collaboration is the heartbeat of Open Source, a symphony where every artisan plays a vital role. By crafting clear, structured channels for community engagement, you ensure that your artifact thrives in harmony. Remember, a well-orchestrated community is the foundation of any great endeavor.

Let the melodies of collaboration guide you forward, traveller. Return tomorrow as the Advent of Open Source continues, and your skills in community building deepen.

Intermediate: Design Templates for Specific Issue Types

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

The Maestro of Synergy approaches with a collection of parchments, each distinct in color and texture. They lay them out on a grand, ornately carved table in the courtyard.

Every voice in the symphony has its own role,

the Maestro begins, gesturing to the parchments.

A melody differs from a rhythm, as each fulfills a unique purpose. In the same way, the voices that join this harmony often seek to express different needs. It is our task to guide them with precision.

They slide one parchment toward you, its edges trimmed with golden thread.

These are the Scrolls of Purpose,

they explain.

Each sheet is meant for a distinct kind of contribution to the harmony. Design these wisely, so every voice may find its place with ease.

You take the parchments, feeling their weight and the responsibility they carry, ready to tailor them for clarity and purpose.

As your Open Source project grows, so does the variety of issues raised by contributors and users. Bug reports, feature requests, and documentation updates all require different information to be actionable, yet a lack of structure can lead to incomplete or unclear submissions. Providing tailored issue templates ensures contributors know exactly what details are needed, saving time for both them and the maintainers. It also enhances the quality of communication, making your project easier to manage and more accessible for newcomers.

Today’s challenge focuses on creating issue templates for different types of contributions—such as bug reports, feature requests, and documentation updates. You’ll also configure a central configuration file to manage how these templates are displayed and add helpful links for contributors. By the end of this challenge, your project will have a professional, structured workflow for handling issues efficiently.

This challenge describes the process for GitHub repositories, but similar features are available in other platforms like GitLab and Bitbucket. Please follow the documentation for your chosen platform to implement issue templates.

  1. Create a directory for issue templates.

    Before creating the templates, check that your repository has a .github/ISSUE_TEMPLATE directory. If it doesn’t exist, create it.

    This directory will contain all your issue templates, organized by type.

  2. Write templates for specific issue types.

    Each template should focus on a specific issue type, such as bug reports, feature requests, or documentation improvements.

    Create a bug report template.

    1. Inside the ISSUE_TEMPLATE directory, create a new file named bug_report.md.

    2. Include fields for the following details:

      • A clear description of the bug.
      • Steps to reproduce the bug.
      • Expected and actual behavior.
      • Environment details (e.g., OS, browser, software version).
      .github/ISSUE_TEMPLATE/bug_report.md
      ---
      name: Bug Report
      about: Report a bug to help us improve
      title: "[Bug] <Short description>"
      labels: bug
      ---
      

      **Describe the bug**
      A clear and concise description of what the bug is.
      

      **To Reproduce**
      Steps to reproduce the behavior:
      1. Go to '...'
      2. Click on '...'
      3. See error
      

      **Expected behavior**
      A clear and concise description of what you expected to happen.
      

      **Environment**
      - OS: [e.g., Windows 10]
      - Browser: [e.g., Chrome 92]
      - Version: [e.g., 1.2.3]

    Create a feature request template.

    • Create another file in the same directory named feature_request.md.

      .github/ISSUE_TEMPLATE/feature_request.md
      ---
      name: Feature Request
      about: Suggest a new idea for the project
      title: "[Feature] <Short description>"
      labels: enhancement
      ---
      

      **Is your feature request related to a problem? Please describe.**
      A clear and concise description of what the problem is.
      

      **Describe the solution you'd like**
      A clear and concise description of what you want to happen.
      

      **Additional context**
      Add any other context or screenshots about the feature request here.

    Create a documentation update template.

    • Similarly, create a documentation_update.md file.
    • Include fields for:
      • The affected section of documentation.
      • Suggested improvements.
      • Links or examples for clarification.

  3. Configure a central configuration file.

    On top of having the template, you can also provide a config.yml file in the ISSUE_TEMPLATE directory to add extra information and guidance for contributors.

    .github/ISSUE_TEMPLATE/config.yml
    blank_issues_enabled: false
    contact_links:
      - name: Project Documentation
        url: https://your-docs-url.com
        about: Please check our documentation before creating an issue.

    This configuration disables blank issues, encouraging contributors to use the appropriate templates.

    It also provides a direct link to your project documentation, helping contributors resolve their questions or issues independently.

  4. Add labels for automatic categorization.

    Use GitHub’s labels to categorize issues automatically based on the templates used.

    Set labels in the templates to ensure each template assigns the correct label with the labels field in its metadata (see examples above).

    Labels like bug, enhancement, or documentation make it easier to triage issues and prioritize tasks.

    Use GitHub’s settings to customize label colors and descriptions, making them more intuitive.

Designing specific issue templates is a small but impactful improvement for any Open Source project. It ensures contributors provide all necessary details upfront, making issue resolution faster and more effective. By guiding contributors through structured forms, you also lower the barrier for participation, encouraging more thoughtful engagement.

Congratulations on completing this challenge! Your project is now better equipped to handle diverse contributions while saving time and effort for maintainers. Keep refining your templates as your community grows.

Success Criteria

  • ✓ Specific issue templates (e.g., bug report, feature request, documentation update) exist in your repository.
  • ✓ A configuration file (e.g., config.yml) provides additional guidance for contributors.
  • ✓ Templates include clear fields.
  • ✓ Labels are automatically applied to issues based on the selected templates.

Returning to the courtyard, you present the set of completed Scrolls of Purpose to the Maestro of Synergy. Their practiced hands inspect each one, their gaze focused yet approving.

You have brought structure to the symphony,

they declare.

Each scroll now reflects the specific needs of those who will join. This precision ensures that the harmony will not falter, even as new voices are added.

Around you, the melodies begin to shift, their complexity growing, yet their balance unbroken. The shadow of the Discord of Miscommunication fades further into the distance.

With each tailored scroll, you deepen the strength of the symphony,

the Maestro continues.

Remember, clarity is the foundation of harmony. Keep refining, and the voices that join will only enrich the melody.

You gather the scrolls, knowing that they will serve as anchors for the growing harmony within the Harmonic Courtyard.

The Maestro’s Wisdom

Collaboration is the heartbeat of Open Source, a symphony where every artisan plays a vital role. By crafting clear, structured channels for community engagement, you ensure that your artifact thrives in harmony. Remember, a well-orchestrated community is the foundation of any great endeavor.

Let the melodies of collaboration guide you forward, traveller. Return tomorrow as the Advent of Open Source continues, and your skills in community building deepen.

Advanced: Use Dynamic Issue Templates

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

The Maestro of Synergy beckons you to the center of the courtyard, where an intricate device sits—a circular frame filled with spinning rings, each etched with countless symbols. The device hums softly, its motion mesmerizing.

This is the Harmonic Lens,

the Maestro explains, placing a hand on the device.

It adapts to the needs of the moment, shifting its focus to offer clarity where it’s most needed. No two voices in the symphony are the same, and so too must our guidance adjust to their unique needs.

They turn the rings of the Harmonic Lens, and its symbols align, glowing faintly.

The path you set must not be rigid,

the Maestro continues.

Instead, let it flow, adapting as the voices in the symphony grow more diverse. With the Lens of Adaptation, you can offer each voice exactly what it seeks.

They step back, leaving the Lens in your care, its rings awaiting your touch.

Managing multiple repositories or a large one with contributors can become a daunting task, especially when issue reports lack structure or clarity. Dynamic issue templates are a powerful way to guide contributors in providing the information you need to address their concerns efficiently. By tailoring the issue submission process to different types of input, you reduce friction for contributors while ensuring that maintainers have all the context they need to act swiftly. GitHub’s dynamic issue forms add flexibility and interactivity to the process, empowering you to use features like dropdowns or checkboxes.

Today’s challenge focuses on creating and implementing dynamic issue templates for your repositories. Whether you’re handling bug reports, feature requests, or other common issues, this task will help you build a standardized, user-friendly issue workflow that saves time for everyone involved. By the end of this challenge, you’ll not only have functional issue forms but also a system that can be replicated or shared across multiple repositories for consistency.

  1. Review your existing issue template.

    Before diving into dynamic forms, take a moment to evaluate your current setup.

    • Are you already using issue templates?
    • Maybe in Markdown?
    • If so, what types do you have (e.g., bug reports, feature requests)?

    Identify gaps in the information contributors typically provide. Look at the issues that often require follow-up questions—these are good candidates for improvement.

    Do the following for each repository:

    • Check if your .github/ISSUE_TEMPLATE directory exists and contains templates.
    • If you don’t have issue templates, check out the other challenges of the day to create them.
    • Consider aligning templates across repositories to provide a consistent experience.

  2. Create dynamic forms.

    Dynamic issue templates are created using YAML files. They allow you to design interactive forms with fields like dropdowns or checkboxes.

    1. Navigate to your .github/ISSUE_TEMPLATE directory (create it if it doesn’t exist).

    2. Create a new YAML file for a specific type of issue, such as bug-report.yml.

    3. Add fields that guide users to provide the necessary details:

      .github/ISSUE_TEMPLATE/bug-report.yml
      name: Bug Report
      description: Report a bug in the project
      title: "[Bug]: "
      labels: ["bug"]
      body:
        - type: markdown
          attributes:
            value: "Thank you for reporting a bug. Please provide the following details:"
        - type: input
          id: reproduction-steps
          attributes:
            label: Steps to reproduce
            description: "List the steps to reproduce the issue."
            placeholder: "Step 1: ..., Step 2: ..."
        - type: dropdown
          id: environment
          attributes:
            label: Environment
            description: "Select the environment where the issue occurs."
            options:
              - Development
              - Staging
              - Production
        - type: textarea
          id: logs
          attributes:
            label: Logs or Screenshots
            description: "Provide any logs or screenshots that may help identify the issue."

    4. Test your form by creating a new issue in your repository and selecting the template you just created.

  3. Standardize templates across repositories.

    GitHub allows you to share issue templates across multiple repositories. If you have a standard set of templates you’d like to use in all your projects, or at least a default one, you can create a .github repository with the templates and then reference them in your other repositories.

    This can be done at the individual or organization level, ensuring consistency and reducing the effort required to maintain templates across multiple projects.

    Learn more about default community health files.

By completing this challenge, you’ve streamlined your project’s issue-tracking system while providing contributors with a better user experience. Dynamic forms reduce ambiguity, allowing maintainers to focus on resolving issues rather than requesting additional information. Standardizing templates across repositories ensures a unified workflow, saving time for both contributors and maintainers.

Congratulations on enhancing the efficiency of your issue management process! Remember, small improvements like these can significantly impact your project’s success.

Success Criteria

  • ✓ At least one repository now uses dynamic issue templates.
  • ✓ Templates are tested and working as expected.
  • ✓ Templates are standardized across repositories where applicable.
  • ✓ Default community health files are used to share templates across multiple repositories.

The Harmonic Lens spins steadily as you return it to the Maestro of Synergy, its symbols glowing brighter than before. The melodies in the courtyard shift and evolve, their tones richer and more intricate.

You have mastered the art of adaptation,

the Maestro says, their voice filled with admiration.

Each adjustment you’ve made ensures that every voice finds its way without confusion. The harmony grows stronger as a result.

The faint shadow of the Discord of Miscommunication flickers and dissipates, unable to withstand the flexibility and clarity you’ve brought.

Remember, the symphony is ever-changing,

the Maestro advises.

By remaining adaptable, you ensure that no matter how the melodies evolve, they will always find balance.

With the Harmonic Lens in hand, you feel confident that the growing symphony will flourish under the guidance of its dynamic structure.

The Maestro’s Wisdom

Collaboration is the heartbeat of Open Source, a symphony where every artisan plays a vital role. By crafting clear, structured channels for community engagement, you ensure that your artifact thrives in harmony. Remember, a well-orchestrated community is the foundation of any great endeavor.

Let the melodies of collaboration guide you forward, traveller. Return tomorrow as the Advent of Open Source continues, and your skills in community building deepen.