Contributing - softgitron/potku-console GitHub Wiki

Contributing to the project

This is a small hobby project maintained by a group of friends and not actively promoted in any way, so first of all, congratulations and heartfelt thanks on finding such an obscure piece of software and on top of that, wanting to contribute.

Before proceeding any further make sure you follow the code of conduct in all your contributions.

Follow the following links to get info on specific ways you can contribute:

If you want to report a bug or suggest a feature, go here

If you want to work on an existing issue, go here

If you have a bug you want to fix or a feature you want to implement yourself, go here

If you want to contribute to the wiki, go here

Opening an issue

When reporting a new bug or suggesting a new feature, opening an issue is the way to go. The core team treats accepted issues as tickets in a backlog, so write a good issue that gets approved into the development queue to ensure your proposed fix or change will end up in the project.

Use the provided issue templates and fill the description to the best of your ability. With bugs pay specific attention to the steps to reproduce and with feature suggestions, the user story.

Issues that are accepted into the development backlog get a specific tag depending on their priority level. You can check your issues for the tag to know whether they have been reviewed and accepted into the development backlog. Issues that are rejected will get a comment on why the issue was rejected.

Working on an issue

If you want to work on an existing issue, feel free to do so. However, when making a pull request, make sure to link the issue you worked on. Also make sure your pull request only concerns one issue, as bigger pull requests are too big for reviewing and will get automatically declined citing the reason "pull request concerning more than one issue".

To make sure your pull request will get approved, make sure it fulfills all the qualities of a good pull request. The pull request will be merged if it is approved.

Commit messages should adhere to the general guidelines found here.

Contributing code with no existing issue

Making a pull request that fixes an unreported bug or introduces a non-documented feature is strictly forbidden.Bugs need to be documented and tested well and new feature implementations into the project are always to be considered by project maintainers. Thus if you want to fix an undocumented bug start with an issue, unless it is a security flaw, in which case follow our security guidelines and if you want to implement a feature without a ticket, fork the repository, and implement the feature in your own fork.

If want to get your feature included in the main project, you have to go through submitting a new issue. You can create a draft pull request linked to the issue before the issue is accepted into development, just make sure to only make the actual pull request after the issue is accepted into development. Don't forget to adhere to the qualities of a good pull request.

The qualities of a good pull request

  • Name is formatted as "Fix #ISSUENUM - ISSUENAME"
  • The pull request comment should explain the main content of the pull request in more depth.
  • All debatable decisions made and other relevant information should be included in the pull request comment.
  • Pull request fixes one, and only one, issue.
  • The code adheres to the style guide.

Getting a pull request approved

At the moment we do not have automated testing in the repository workflow, but that will be added in the future. Before that an approved code review from 2 project maintaners is required. Merging approved requests is the responsibility of project maintainers.

Pull requests not deemed up to the project standards will get commented for improvement suggestions so don't be afraid to make one. Good communication and a healthy approach to criticism is the most important part in any contribution, we are not experts and neither do we require expert level contributions. We try to stick to these strict guidelines precisely because we are not experts, so don't worry and just contribute. All effort towards a better end result is appreciated, no matter your level of expertise.

Wiki contribution

The repository has specific issue templates for documentation updates and documentation additions. Documentation should be only written by project maintainers, so if you wish for changes in the wiki, just open an issue and wait for the project maintainers.

Project maintainers may make small documentation updates without opening an issue, but must open an issue for bigger changes. Common sense is recommended here, a few lines or small typos is a fine impromptu change, but adding three new files is definitely worth an issue. Generally changes that affect the structure and functionality should go through an issue, while small additions like keeping up with changing code or fixing typos should not. Project maintainers may push straight into the wiki repository, without branches and pull requests and may close the issues after pushing.