Maintainer Responsibilities¶

Overview¶

The maintainer for an open-source project fulfills many responsibilities, including setting up the project, managing issues, reviewing submittals, and leading the development community. In addition, the maintainer is often a prime contributor.

Establish Repository¶

The maintainer shall work with the sponsoring SDO to establish the open-source repository for the project.

Configure Project Settings¶

Issues and Discussions¶

The maintainer shall ensure that the issues and discussion pages are enabled for the ITS open-source project.

Pages¶

If the project includes documentation, the maintainer shall ensure that GitHub pages is enabled for the project.

Dependabot¶

If the project includes code, the maintainer may configure Dependabot to report issues or create pull requests to update dependencies with security vulnerabilities.

Set Up Project Files¶

Overview¶

The maintainer shall ensure the following files are provided in the repository when starting the project and maintained throughout the project:

• README.md
• CODE_OF_CONDUCT.md
• CONTRIBUTING.md
• LICENSE.md
• SECURITY.md
• .github/CODEOWNERS
• appropriate issue templates in .github/ISSUE_TEMPLATE/
• appropriate PR temapltes in .github/PULL_REQUEST_TEMPLATE/
• appropriate saved replies

Additionally, if the site includes documentation, the maintainer shall ensure the following files are provided in the repository when starting the project and maintained throughout the project:

• .gitignore
• mkdocs.yml
• .github/workflows/deploy.yml (generates the documentation)
• docs/index.md
• docs/stylesheets/extra.css
• overrides/main.html (adds a status badge to the page)
• overrides/partials/nav.html (changes the naviation heading to be "Contents")
• overrides/partials/toc.html (changes TOC heading to be the document name)

Finally, the site shall include installation guidance, which may be contained in the README.md file, a separate INSTALLATION.md file, or in project documentation.

Readme.md File¶

The README.md file shall contain an introduction to the open-source project. A good readme file should be clear, concise, up-to-date, and detailed. This file is located in your root directory and is displayed as the homepage of the repository within GitHub.

The README.md file shall contain the following information:

• project title
• information on how to access the current documentation for the project
• information on how to access prior releases of the project
• project summary, including its status and overview
• Acknowledgements of relevant funding sources, sponsors, and other open-source projects
• installation guidance
• tech and tools used in the project
• link to the code of conduct
• link to discussion forum for the project
• link to the issues page for the project and the types of issues accepted for the project
• link to the contributing guidelines
• link to the open source license

• OpenSauced App
• Astro documentation
• freeCodeCamp
• ITS Open-Source Process

Installation Guidance¶

The installation guidance may be contained within the README.md file (e.g., if it is simple), be a separate file, or reference a section within the project documentation.

This guide identifies the tools and technology used by the project and includes instructions for the following:

• forking the repository
• cloning the repository
• installing the dependencies
• setting up the environment variables
• setting up the database, if applicable
• running the project locally

The best way to test your guide is by setting up the project locally using your guide. If you encounter issues getting your project to work, you will discover it quickly and can update the documentation to add or clarify the missing piece.

Code of Conduct File¶

The CODE_OF_CONDUCT.md file shall define the rules and behaviors that are to be followed for the project.

The CODE_OF_CONDUCT.md file should consist of a reference to the ITS Open-Source Code of Conduct with any exceptions and extensions identified.

Contributing File¶

The CONTRIBUTING.md file shall define the rules for contributing to the project.

The CONTRIBUTING.md file should consist of a reference to the ITS Open-Source Contributor Responsibilities with any exceptions and extensions identified.

The CONTRIBUTING.md file should identify specific types of conventions that apply to the project.

License File¶

The LICENSE file shall be a well-known Free and Open Source license.

For NTCIP documentation projects, including standards and ASN.1, the license should be CC BY 4.0.

For NTCIP projects involving code for a computer program, the license should be the Gnu Lesser General Public License Version 3.

Security file¶

The SECURITY.md file shall indicate how to provide reports of security issues through private channels to prevent exposure of the vulnerabilities prior to their fix.

Code Owners File¶

The .github/CODEOWNERS file shall conform to the rules defined in the official GitHub documentation.

This ensures that the correct maintainers are notified when PRs are submitted.

Issue Templates¶

The maintainer shall define appropriate issue forms.

The maintainer shall develop the forms using YAML per the GitHub instructions.

Pull Request Templates¶

The maintainer shall define appropriate pull request templates.

Saved Replies¶

Sometimes, you repeatedly write the same reply to issues or pull requests. Clear communication between maintainers and contributors is crucial. So, when you write all comments manually, your messages will no longer be consistent and may be unclear. You can create saved replies when you frequently respond to issues and pull requests with the same comments.

Saved replies allow you to create a reusable response to issues, pull requests, and discussions and use it across repositories. It will save you time responding to contributors while keeping the consistency of your message. You can always modify your replies if necessary.

Read the GitHub documentation for complete instructions about how to create saved replies.

Gitignore File¶

If there are any files that are likely to exist within the project directory that should not become a part of the repository, the maintainer shall include a .gitignore file.

Mkdocs.yml File¶

If the project includes documentation using MkDocs, the maintainer shall define a mkdocs.yml file.

Deploy.yml File¶

If the project includes documentation using MkDocs, the maintainer shall define a .github/workflows/deploy.yml file that deploys the MkDocs site to GitHub Pages.

Index File¶

If the project includes documentation using MkDocs, the maintainer shall define a docs/index.md file that provides a cover page for the document.

Extra.css File¶

If the project includes documentation using MkDocs, the maintainer shall define a docs/stylesheets/extra.css file that defines the heading styles to be used for the body and the annexes (i.e., adding setion numbers in front of headings).

The maintainer shall ensure that this badge only changes per the approval process defined for the project.

Main.html File¶

If the project includes documentation using MkDocs, the maintainer shall define a overrides/main.html file that provides a badge that identifies the status of the project files.

The maintainer shall ensure that this badge only changes per the approval process defined for the project.

Nav.html File¶

If the project includes documentation using MkDocs, the maintainer shall define a overrides/partials/nav.html file that overrides the title assigned to the left-hand navigation menu to be "Contents".

Toc.html File¶

If the project includes documentation using MkDocs, the maintainer shall define a overrides/partials/toc.html file that overrides the title assigned to the navigation menu on the right side of the screen.

Define Project Structure¶

Once the project is established, configured, and the loaded with the initial project files, the maintainer shall establish the plan for the project by defining issues along with any appropriate stub files that can provide further guidance.

Issue Triage¶

Overview¶

Once issues are being created for the project, the maintainer will need to triage these issues to ensure that they contribute to the project plan and so that they can be claimed by contributors.

Learning to triage issues is essential for any open-source maintainer. This involves going through the existing list of open issues and prioritizing them in order of importance. Some open issues will be critical bug fixes, while others might be nice to have feature requests. Sometimes, you might have issues opened for things that are not a right fit for the project.

Triage Pre-Assessment¶

Overview¶

Prior to performing any detailed triage, it is important to screen reported issues that are not appropriate for further investigation.

Dealing with Spam¶

When a comment is spam, clearly combative, or unhelpful, the maintainer should avoid direct engagement, label the issue as spam, close the issue, and move on.

Insufficient Information Issues¶

When a comment does not provide concrete details about the issue, the maintainer should respond by requesting more information.

If the commenter does not respond within a week, the maintainer should message them again for more details.

If a few weeks pass and the issue is not considered critical, the maintainer may close the issue.

Stale Issues¶

The maintainer may may label issues that have not been worked on for months as stale.

If the maintainer wishes to resurrect a stale issue, the maintainer shall go through the normal triage process, including adding and removing labels as appropriate.

If the maintainer believes a stale issue no longer applies, the maintainer should close the issue. This process may be automated (e.g., using an action like Close Stale Issues and PRs.

Ensuring Proper categorization¶

For issues that have sufficient information and are not spam or stale, the maintainer shall add and/or remove labels as appropriate for proper management.

The following labels should be considered for most specification projects:

1. General Type Labels

   • github automation: an issue related to the automated github scripts in testing or generating the documentation.
   • question: Indicates a general inquiry or a request for clarification about how something works. Questions should be moved to the discussion tab, but the issue can be labeled with question and closed.

2. Type Labels for Documentation

   • documentation bug: Identifies a reported problem or flaw in the documentation.
   • documentation enhancement: Refers to a suggestion or request to improve or add informative text in the documentation.
   • new user need: Suggests a new user need to be added in the document.
   • user need modification: Suggests a modification to a user need in the document.
   • new requirement: Suggests a new requirement to be added in the document.
   • requirement modification: Suggests a modification to a requirement in the document.
   • dialog modification: Suggests a modification to a dialog in the document.
   • ASN.1 modification: A change to the ASN.1 or MIB.

3. Type Labels for Code

   • bug: Identifies a reported problem, flaw, or unexpected behavior in the code.
   • enhancement: Refers to a suggestion or request to improve or add features to the project.
   • feature: Used for issues proposing new functionality or significant changes.
   • refactor: A change in the codebase that improves its structure or readability without altering its functionality.
   • test: Issues related to unit tests, integration tests, or overall testing improvements.
4. Priority Labels (Help prioritize issues based on urgency or importance)
   • critical: Indicates urgent issue related to an existing release that needs to be addressed immediately (e.g., perhaps requiring its own release to formalize in a timely manner).
   • high priority: Indicates urgent issue that needs to be addressed as soon as possible to allow for other tasks to proceed for the current update but not critical.
   • medium priority: Important issue to address prior to next release that relates to functionality but not high priority.
   • low priority: Non-urgent issues that may be tackled if there’s extra time or resources available.
5. Status Labels (Track the progress of an issue or pull request)
   • in progress: The issue is currently being worked on.
   • blocked: Work on this issue is delayed or cannot proceed due to a dependency or external factor.
   • needs discussion: Indicates that the issue or pull request requires further conversation or clarification before proceeding.
   • triage: Newly created issues that need to be reviewed, categorized, and prioritized.
   • ready for review: The pull request is awaiting review by project maintainers.
   • duplicate: Marks an issue as being identical or closely related to an already existing issue.
   • wontfix: Indicates that the maintainers have decided not to address the issue, either due to scope, relevance, or priority.
6. Difficulty or Effort Labels (Classify the expected effort required to address the issue)
   • good first issue: Meant for new contributors; these are usually easy-to-solve problems with clear instructions.
   • beginner-friendly: Similar to “good first issue,” these are relatively simple problems that beginners can address.
   • help wanted: Indicates that maintainers need assistance with the issue, open to contributions.
   • complex: Issues that are challenging, requiring significant experience or effort to resolve.
7. Version or Milestone Labels (Track issues by release or milestone)
   • compatibility: Associates an issue or pull request with a specific version or release milestone.
   • next release: Indicates that the issue is planned for inclusion in the upcoming release.
   • future: Refers to issues or features planned for future releases beyond the current roadmap.

Triaging Bugs¶

The maintainer should verify the existance of any reported bug.

Triaging Feature Requests¶

The maintainer shall ensure that any new feature request fits into the vision for the project.

The maintainer shall communicate with the original poster of the issue to determine how to best deal with the issue, including:

• assigning to the originator, if they express a willingness to contribute a solution,
• assigning to the originator and someone else (e.g., a maintainer), if the originator is willing to contribute to a solution but is unwilling to develop and propose it,
• adding a help wanted, if the maintainer wishes to look for another contributor, or
• assigning it to himself or another core team member, if the maintainer expects the issue to be addressed by them in a timely manner.

Triaging Duplicate Issues¶

When assigning a duplicate label, the maintainer should respond to the originator of the issue.

Triaging Rejected Issues¶

When assigning a wontfix label, the maintainer should respond to the originator of the issue.

Reviewing Pull Requests¶

Overview¶

It is the maintainer's responsibility to ensure that the suggested code or documentation update meets the standards of the project and doesn't introduce any new issues for the project. You will also need to work with the contributor to help solve issues they encounter.

Pull-Request Pre-Assessment¶

Spam Pull Requests¶

For any pull request deemed to be spam, the maintainer should label the request as spam, close the pull request, and not respond to the contributor.

• whitespace changes to the README file or other files
• random changes to files without an accompanying issue or explanation
• numerous links to unrelated websites or promotes products/services
• plagiarized content from other sources without permission or proper attribution

Low-Quality Pull Requests¶

For a pull request deemed to be of low quality, the maintainer should reach out to the author, explaining what needs to be added and what changes need to be made.

• unfinished pull requests that do not address the entire issue
• code that does not fit within the established style guide for the project
• incomplete pull request forms that do not provide sufficient information on what changes were made
• address multiple issues at once and make it challenging to review

Stale Pull Requests¶

If the maintainer is unable to get a response from a contributor regarding an issue after a repeated attempts over several weeks, the maintainer may reassign the associated issue; if there is an associated pending pull request, the maintainer shall either close the pull request or take it over (i.e., by using the code in the pull request as the starting point for additional modifications).

Testing¶

Overview¶

The maintainer shall review each contribution to ensure that all tests pass, the contribution works as expected without introducing errors.

Automated Testing¶

The maintainer should maintain automated tests to protext against errors.

Failing Automated Tests¶

If a maintainer receives a pull request that fails automated testing, the maintainer should wait a few days to allow the contributor to resolve the issue independently.

If the contributor does not resolve the issue within a few days, the maintainer shall contact the contributor to see if they need help.

If the failing test is unrelated to the contributor's changes, the maintainer shall let the contributor know that the error is safe to ignore and that it will be fixed in another pull request.

If the contributor fails to respond after repeated attempts over several weeks or months, the maintainer should close the pull request and move on.

Code Reviews¶

Prior to accepting any pull request, the maintainer shall review all proposed changes to ensure that they are designed to address the reported issue as claimed and that they conform to the projects coding and documentation guidelines.

Manual Testing¶

Prior to accepting a significant pull request, the maintainer should manually test the project using his local machine.

Effective Feedback¶

If the maintainer discovers a problem with the pull request, the maintainer shall respond to the contributor with a detailed account of the problem.

The maintainer shall indicate the importance of each problem identified in the contribution with critical, high, medium, or low.

Missing Tests¶

Significant contributions of code should be accompanied with tests to help ensure that everything is working as expected.

Creating a Release¶

The maintainer shall create a formal release for each version of the document approved for release by the responsible WG or committee.

The maintainer shall assign a tag to the release that indicates the version number per Semantic Versioning 2.0.0.

The maintainer shall attach a PDF and zip archive of the website in versioned directories in the gh-pages branch.

gh-pages/  
├── index.html (latest version)  
├── v1.0.0/  
├── v1.0.1/  
├── v1.1.0/  
└── v2.0.0/

name: Deploy MkDocs Site and Generate PDF
on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

- name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.x'

- name: Install dependencies
        run: |
          pip install mkdocs-material
          pip install weasyprint

- name: Build MkDocs site
        run: mkdocs build

- name: Generate PDF
        run: |
          weasyprint site/index.html site/docs.pdf
        env:
          WEASYPRINT_BASEURL: 'https://yourusername.github.io/repository-name/'

- name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site

- name: Upload PDF to release
        if: github.ref_type == 'tag'
        uses: actions/upload-artifact@v3
        with:
          name: docs-${{ github.ref_name }}.pdf
          path: site/docs.pdf

Building a Community¶

Overview¶

A vital component of any open source project is its community. Building a strong community can help accelerate the growth of your open source project. As new contributors discover and start to contribute to your project, you will want to create spaces for communication and collaboration.

If your project is on GitHub, you can use GitHub Discussions as a way for contributors to post questions and facilitate conversations. WG meetings should be advertised on the discussion board to encourage participation.

Promptly Respond and Address Concerns¶

Maintainers should establish a schedule to review incoming issues and pull requests and post this schedule within the discussion forum.

The maintainer should set up GitHub Actions to automate responses that welcomes each new contributor and provides an estimated time by which the issue triage or PR review can be expected

Advanced Features¶

Overview¶

Leveraging GitHub Actions to bring Continuous Integration / Continuous Delivery or Deployment (CI/CD) into your workflow directly in your repository will let you run code, test, build, and deliver or deploy software with simple and secure workflows. Automating these tasks will speed up your deployment process.

Using Git, GitHub, and GitHub Actions to build a CI/CD pipeline should give you confidence in your code.

Below are some helpful resources to help you build a CI/CD pipeline with GitHub Actions:

• GitHub Docs: The complete CI/CD solution
• How to build a CI/CD pipeline with GitHub Actions in four simple steps

There are many types of actions that you can set up for your project, depending on what you need. Below are some GitHub Actions that you usually find across repositories:

Linter¶

Most open source repositories have linters that run on each pull request. Linter is a tool for detecting potential errors and maintaining a consistent code style in a project. Super-Linter is one of the most used actions. This action can help you maintain code quality and achieve a more readable and consistent style.

Code Scanning Tools¶

Code scanning is a tool for detecting security vulnerabilities, possible bugs, and errors in code. You can use GitHub's code scanning feature and configure tools like CodeQL, which GitHub maintains, or third-party scanning tools such as SonarQube.

Creating and Customizing Actions¶

Actions of note:

• GitHub Marketplace
• Take Action: allows contributors to assign themselves to an issue by typing the .take command in the issue's comment.
• Triage Action: blocks the Take Action whenever a needs triage or core team work label exists.

You can read more about GitHub Actions and how to create one in the official documentation.

Projects¶

Keeping track of your issues is getting more challenging as your project progresses. A great tool that can help you organize and track your issues is Projects on GitHub. With projects, you can efficiently manage your project's features, roadmaps, or releases as they're built from and integrated with issues and pull requests that you add.

You can choose a template for your project. One of the templates is the "Kanban" template. Here, you can create notes and place the existing issues and pull requests in the "Backlog", "Ready", "In progress", "In review", and "Done" columns. This will make it easy for you and your team to track the progress of your project.

To create a new project:

1. Navigate to your GitHub profile and click the "Projects" tab.
2. Click the green "New project" button.
3. Choose a template.
4. Name your project and click the "Create project" button at the bottom.

Please read the GitHub documentation to learn more about adding items to your project.