Commenter Responsibilities¶

Overview¶

General¶

Comments on projects using the ITS Open-Source Process are always welcome, no matter how seemingly major or minor. Comments are key to improving products. The ITS Open-Source Process is designed to facilitate and encourage users to submit comments and therefore the commenting process is kept simple.

Within the ITS Open-Source Process, comments can be submitted in either the discussions or issues tab of the project repository.

Discussions¶

The discussions tab provides an open forum where interested parties can discuss ideas, ask and answer questions, and formulate ideas. The discussions tab does not directly propose any change to the project but can often nurture ideas that ultimately result in refining the overall vision of the project, identify problems or ambiguities in the project contents, develop consensus on project priorities, etc.

Discussions can be started by anyone at any time. Discussions can result in refining the concept of one or more issues before formally submitting them as issues.

Issues¶

Every project should follow a plan. Within the ITS Open-Source Process, the plan is documented by defining issues that are to be addressed, preferably according to assigned priorities.

The issues tab provides an open forum where any interested party can propose specific issues that need to be addressed by project contributors. The issues can be anything from a missing comma to requesting an entirely new feature. All proposed changes to a project are supposed to be initiated by submitting an issue.

When an issue is submitted, the project maintainer is responsible for triaging the issue. Triaging includes reviewing the issue, determining if the issue fits within the project plan, potentially parsing or merging the issue to create easily manageable tasks, assigning appropriate priority and tags (e.g., bug, ambiguity, editorial) to the issue, and gaining consensus on the approach. This process can involve working with others on the project team to ensure consensus on the decisions being made.

Once an issue has been reviewed and accepted, anyone can claim ownership of the issue and begin resolving it. Given the complexities of version control when there are potentially multiple contributors, it is wise to separate issues into distinct bite-sized tasks that can be addressed with a reasonably short turn-around.

Submitting a Comment¶

Read the README file¶

Before commenting, commenters should be familiar with the project as documented in the README file.

Respect the CODE_OF_CONDUCT¶

When commenting, commenters shall respect the rules within the CODE_OF_CONDUCT file.

Use discussions if no change is proposed¶

For comments that do not actively propose a specific change to the project, the commenter shall initiate a discussion using the project's discussion template.

Use issues to propose changes¶

For comments that actively propose a specific change to the project, the commenter shall submit an issue using the project's appropriate issue template (e.g., bug fix, documentation improvement, new feature).

Comply with templates¶

The commenter shall comply with all instructions on the selected commenting template without deleting any fields.