NA

CONTRIBUTING Guidelines

Welcome to the United4Surveillance signal detection tool repository! We’re excited to have you contribute to our open-source project. Before you get started, please take a moment to read through the following guidelines to ensure a smooth and productive collaboration.

Table of Contents

  1. Code of Conduct
  2. How to Contribute
  3. Coding Guidelines
  4. Commit Message Guidelines
  5. Branching Strategy
  6. Documentation
  7. Testing

Code of Conduct

Please note that this project adheres to the Code of Conduct. By participating in this project, you agree to abide by its terms.

How to Contribute

We welcome contributions from the community! Whether you’re reporting a bug, suggesting an enhancement, or submitting a pull request, your input is valuable to us. Please follow the guidelines below when contributing:

Reporting Bugs

  • Before submitting a new bug report, please check the existing issues to see if the bug has already been reported.
  • Use our bug report template to provide necessary details about the issue, including steps to reproduce and expected behavior.

Suggesting Enhancements

  • If you have an idea for an enhancement, open an issue using our feature request template.
  • Describe the enhancement in detail, including its use case and benefits.

Working on Issues

  • You may assign yourself to an issue if nobody else is assigned yet and you are ready to start working on the issue
  • Make sure to solve the issue according to the specified requirements
  • If you don’t agree with the definition of the issue or problems arise while working on it, comment on the issue to clarify.

Submitting Pull Requests

  • If you are not a maintainer or owner of the repository, please fork the repository and create a new branch from main or the relevant feature branch.
  • Switch the branch to which to merge the Pull Request from the default main to develop. main contains the current released code and we are working on develop.
  • Ensure your code adheres to our coding guidelines.
  • Make sure that your branch entails all relevant previously merged changes and your code is compatible to what is on the main branch. Having started from an old state is not an excuse to push outdated code.
  • Include tests if applicable, and ensure all tests pass.
  • Ensure that all checks which are automatically performed on your PR by Github Actions succeeded. If they did not understand the issue and fix the problem and commit again.
  • Please write a short bullet point what you fixed, added etc. into the NEWS.md file above the header of the latest version. This helps us to keep an overview of all changes for the next release. If it is a really minor change not worth mentioning you do not need to write a note.

Reviewing Pull Requests

  • A pull request may only be merged after a review by another contributor
  • You may assign yourself as an reviewer of a pull request, if you are not its author
  • Please take a close look at the commits and the issue related to the PR
  • Start the app and run it with the test dataset. Check whether all main functionalities, such as running stratified signal detection and running the report still work.
  • Accept the PR if it solves the problem outlined in the feature request issue, adheres to the coding guidelines and is up to date on the current main HEAD.
  • If any tests fail, reject the PR
  • Use github’s PR review functionality and provide constructive feedback

Coding Guidelines

  • Follow the tidyverse style guide to maintain code consistency. The RStudio addin styler can help you with that.
  • As an enhancement to the tidyverse style guide, we will make explicit use of namespaces in order to avoid conflicts and improve clarity (i.e. write dplyr::filter() and stats::filter())
  • We stick to this pipe operator %>%
  • Write clear and descriptive code comments
  • For documentation use roxygen comments.
  • Keep dependencies updated and minimize external dependencies where possible.
  • For repository structure use devtools package skeleton
  • Run an R-CMD Check using devtools::check() locally before submitting your PR. This helps you already to identify and fix problems. An R-CMD Check will also be initiated automatically after your PR submission as this is one of our Github Actions.
  • The code should be compatible/runnable with R-version 4.0.2

Commit Message Guidelines

  • Use meaningful commit messages to convey the purpose of your changes.
  • If longer descriptions are necessary, separate the subject from the body with a blank line for clarity.
  • Reference related issues or pull requests where necessary.

Branching Strategy

  • Create feature branches for new features or enhancements and bug branches for fixing issues.
  • Branch your feature branches off from develop as this contains most recent developments.main is the branch used for releases and should always stay stable.
  • Branch names should be descriptive and follow the format: feature/your-feature-name, bug/issue-number.
  • Ideally, finished work from new branches should be reviewed before merging (see pull requests), even if changes were made by a maintainer or owner. If there are only minor changes, you may merge without a review. Use common sense.

Documentation

  • Maintain and update the project’s documentation as needed.
  • Document new features, changes, and usage instructions.

Testing

  • Write unit tests and integration tests for new features and bug fixes.
  • Ensure all existing tests pass before submitting a pull request.
  • Include testing instructions in the pull request if necessary.
  • Use the testthat package for writing tests

Thank you for contributing to the United4Surveillance signal detection tool!