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.
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!
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.
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.
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.
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.
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 |
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.
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 request template is available to make documenting PRs more consistent and streamlined. Each PR description should include:
Number of the appropriate issue the pull request closes or references.
Brief description of implemented changes, what they do and what is the reasoning behind the changes.
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.
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.).
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.
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.
Each pull request must be accepted by at least one reviewer before it can be merged to the main branch.
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.
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.