Skip to content

Contributing

Jump to bottom
Dave Nicolette edited this page Mar 17, 2021 · 18 revisions

Home -> Developer Guide ->

This document was last updated on March 17, 2021.

General guidelines for contributing to the Cobol Check project, subject to change based on team agreements.

Team Roles and Responsibilities

Tester

An interested party who exercises the product from the perspective of a user and attempts to discover edge cases and other conditions that cause the product to operate incorrectly or to fail altogether. A tester intentionally tries to make the product fail, and also pays attention to usability issues, inconsistencies and inaccuracies in the documentation, and any other factors that may affect users of the product. A tester submits detailed test reports to help the development team understand issues and defects in the product. A tester need not be a contributor or maintainer.

Localization Specialist

A native speaker of one or more languages who contributes to the project by translating and/or reviewing translations of localized text, such as log messages and error messages. An ambitious localization specialist may choose to translate the User Guide or other documents, as well.

Contributor

A software developer who contributes to the code base, but does not have direct commit privileges. Contributors use the pull request process to submit changes to the project. A mentee or intern who has limited professional experience may be accepted in the contributor role. In addition, an experienced developer who is unfamiliar with techiques pertaining to continuous integration, automated testing, trunk-based development, or test-driven development, or who is new to the Java language, the Cobol language, the Gradle build tool, Git, or Github, may work in this role.

Maintainer

Also known as a committer and/or reviewer. A software developer who contributes to the code base and can commit directly to the main branch. Also responsible for reviewing pull requests from contributors and others. A maintainer differs from a contributor in that he/she understands how to write executable test cases or "checks" and how to run the executable test suite, as well as how to perform manual testing to ensure regressions are not introduced into the code base. A maintainer can also review code submissions for consistency with coding standards and naming conventions. A maintainer has access to update the documentation on the project wiki.

Technical Lead

A maintainer who has two additional responsibilities:

  • ensure the direction of development remains consistent with the project's purpose; and
  • represent the project team with the Open Mainframe Project (OMP), and ensure the project conforms with OMP guidelines and requirements.

How We Use Github Issues

We use the issues feature of Github as a lightweight product backlog or list of possible enhancements, as well as to note and track defects. We are not using a separate project management tool or kanban board.

By convention, the name of each issue begins with the version number we are targeting for completion of the item. This is always subject to change, but it provides a general idea of when things are expected to be completed, to help team members decide which items to pull. Issue names look something like this:

[0.5.0] Thing to be done

It means the thing to be done is expected to be included with version 0.5.0.

Github can connect commit messages with issues. We use that feature for tracking progress on issues. By convention, we connect commits with issues by including the issue number at the beginning of each commit message.

  • item #nnn - the commit represents progress on this item (issue number) but does not close it
  • closes #nnn - the commit completes a development or bug fix item

Examples:

git commit -m "closes #234 support for mocking CALL statements"

git commit -m "item #308 partial support for recursion, toggled off (safe)"

Recommended Reading and References

Clone this wiki locally