Skip to content

Latest commit

 

History

History
76 lines (54 loc) · 6.84 KB

CONTRIBUTING.md

File metadata and controls

76 lines (54 loc) · 6.84 KB

Thank you for your interest in the aNCA application! We strive to provide open-sourced for performing Non-Compartment Analysis for both pre-clinical and clinical datasets, aiming to make NCA straightforward and approachable to all scientists.

Report bugs and suggest enhancements

Discussions regarding the project are handled using issues system directly on GitHub. If you wish to create a bug report, suggest changes and additions, or just ask questions regarding the project feel free to open a new issue. Templates for specific topic are available, so please try to select the appropriate one and follow the guidelines as close as applicable.

In general, any posted issue should contain a brief description of the problem, as well as your expectations - we design this application with user-friendliness in mind, we wish to hear your opinion!

Submit changes

Joining the project

In order to gain privileges to commit changes to the codebase, you will need to be added as a collaborator. To do so, please contact one of the contributors. You can find the list with contact info in the DESCRIPTION file.

Issues

Before creating any changes, please make sure an appropriate issue thread is opened. This is the place to discuss the topic at hand, agree on the approach for solving the problem and keep the tasks organized across the whole project.

To keep things organized, GitHub Project board is used.

Status

Each new issue should go to Backlog. Feel free to add not only any bugs and feature requests, but also loose ideas - this is also a space for discussing proposals and validity of implementing them. When committed to implementing a change, the issue is moved to Todo status, and subsequently to In progress when a feature branch is created and work has begun. When the change is ready and the pull request is open, issues should be moved to Needs review where it will be picked up by a reviewer and moved to In review. After the change is merged and issue is closed, it will be moved to Done.

Priority

The tasks are prioritized based on a variant of the MSCW method. It gives a verbose descriptions for each level of priority:

  • MUST - task of highest priority, must be implemented for the application to be usable and useful.
  • SHOULD - task that we should include in the ready product, but it will not be breaking if it is not implemented.
  • COULD - things that would be nice to have and useful, but not instrumental to the whole package.
  • WISH - ideas that are not valid for the time being, but are nevertheless cool and could become useful as the development progresses.

Branches

Each change should be implemented on a separate branch. Branches should have related issues opened and be named after the issue topic. Branch name should include change type (bug/enhancement/documentation etc.) and name of the solved issue. Examples:

Issue Branch
Documentation: add CONTRIBUTING.md file documentation/add-contributing-md-file
Bug: help widget not working bug/help-widget-not-working

Code guidelines

The codebase follows the general tidyverse guidelines, but with lenient implementation. Please do make an effort to make your code clean, readable and easily understandable for the reviewer. In general, as long as your code passes all the lintr tests, you are good.

Commit messages

Do try to follow the conventional commits convention whenever possible. That said, software development is messy and if you feel like this standard does not suit the situation, feel free to deviate from it, but do keep the commit messages short and meaningful at the very least.

Pull requests

Pull request template is available to make documenting PRs more consistent and streamlined. Each PR description should include:

Issue

Number of the appropriate issue the pull request closes or references.

Description

Brief description of implemented changes, what they do and what is the reasoning behind the changes.

Definition of Done

Checklist with minimal requirements to consider the feature or bugfix complete. Preferably the list supplied with the appropriate issue. Requirements might change and the scope might grow or shrink during development, so feel free to make changes to the list if relevant, but make sure any deviations are documented.

How to test

Instructions on how to test the new feature manually (go to..., click on...). Might include code snippets. It is especially important to include such instructions if submitted code is not fully covered by unit tests. If full suite of unit tests is supplied alongside logic, this part might not be required or relevant in terms of miscellaneous changes (documentation, dependencies etc.).

Developers checklist

This part is here as a reminder to perform basic tasks and checks before the code is submitted, to ensure compliance with the guidelines. Before opening a PR for review, please make sure that:

  • Code passes lintr checks
  • Code passes all unit tests
  • New logic covered is by unit tests
  • New logic is documented

The above rules will help keep our work organized, as well as allow for quick information flow between related issues, branches and pull requests.

Notes to reviewer

If there is anything that the reviewer should know before tackling the pull request, please provide it here. This could include things like pointing to specific parts of the code that require special attention, explaining decisions behind unusual implementations or providing logic behind changing the scope of the task.

Code review

Each pull request must be accepted by at least one reviewer before it can be merged to the main branch.

For reviewee

When the change is done, pull request is open and the description is filled, please move your issue from In Progress to Needs review status, so it can be picked up by a reviewer. From this point it is up to the contributor and the person validating the change to work out any kinks and lead to merging the changes.

For reviewers

When reviewing a pull request, please do try to follow the conventional comments guidelines. Ideas and labels described in that convention can be very helpful in getting your thoughts across and facilitate meaningful cooperation. That said, they are not applicable in every circumstance and you are free to do whatever you feel is suitable, as long as it aims to provide valid discussion.