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. The version numbers are defined as milestones for the project on Github. That enables us to filter the list of issues by milestone in order to see which issues are of higher priority.

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. There is a milestone defined with the name "[0.5.0]" to enable filtering by milestone.

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)"

Developer Work Flows

Tester Work Flow

Install the product as a user would do, by downloading the distribution archive for the latest release. Then, let your evil little tester's mind run wild. Document your findings and share them with the development team.

Localization Specialist Work Flow

Clone the repository, or view the localized message files online. They are located in:

src/main/resources/messages

Bear in mind Java class names and method names are not translated.

Submit a pull request or send an email with your corrections and new translations.

Work Flows by Team Role

  1. Clone the repository.
  2. Create a branch for your changes.
  3. Make changes locally and test them. We prefer that you use a test-first approach starting at the unit level and adding integration tests as needed to cover your changes. If necessary, update the approval test so it takes your changes into account.
  4. Open a pull request.
  5. Discuss feedback from reviewers and incorporate their suggestions as appropriate.

Maintainer Work Flow

  1. Clone the repository.
  2. Work in the main branch.
  3. Test your changes locally as thoroughly as you can.
  4. Commit your changes.

Recommended Reading and References

Clone this wiki locally