Skip to content

Contributing

Jump to bottom
oakmount66 edited this page Sep 21, 2023 · 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)"

Work Flows by Team Role

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.

Contributor Work Flow

  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.

Testing changes in the VS code extension

The VScode extension is a part of the git repository and you can find it under the folder ./vs-code-extension.

To setup node modules you must be in the extension directory and here execute the command

npm install

Debugging

The easiest way to test your changes in an extension is to debug it. The debugger is build into VScode with support from the above installed npm packages. VScode extensions can be written in both Javascript and Typescript, but we prefar Typescript.

In some cases you also need to compile the Typescript code before you can debug it. This is done by the command

npm run compile

Hereafter open one of the Typescript files like extension.ts and hit F5 to start debugging the Cobol Check VScode exention. If you are asked to choose debug environment choose "VS Code Extension Development"

Creating a .vsix file.

Another way to test your extension changes is to create a .vsix file and install the extension in your VScode. Read much more here.

In short:

  1. Open a command prompt
  2. Place yourself in the vs-code-extension directory
  3. Issue the command
vsce package
  1. A cobol-check-extension-M.m.F.vsix will now be located in the ./vs-code-extension directory and you can now open VScode and install it here or you can install it via the command
code --install-extension cobol-check-extension-M.m.F.vsix

here M.m.F is your Major, minor and Fix number set as version in the package.json file.

Recommended Reading and References

Clone this wiki locally