Contributing to TrenchR

Thanks for taking the time to contribute!

The following is a set of guidelines for contributing to TrenchR. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.

Table Of Contents

Code of Conduct

What should I know before I get started? * TrenchR

How Can I Contribute? * Ready to develop * Reporting Bugs * Suggesting Enhancements * Your First Code Contribution * Pull Requests

Styleguides * Git Commit Messages * R Styleguide

Additional Notes * Issue and Pull Request Labels

Credit

Code of Conduct

As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities. We welcome and appreciate all contributions regardless of contributor identity or level of experience. We adhere to the Contributor Covenant (http:contributor-covenant.org).

What should I know before I get started?

TrenchR

TrenchR is an open source project — it’s made up of over 10 modules. If you are considering contributing to TrenchR, this section should help you with that.

TrenchR is modular. The R scripts cover a particular category (aka modules), and each have multiple function definitions.

Here’s a partial list of modules:

How Can I Contribute?

Development

  • Fork this repo to your Github account
  • Clone your version on your account down to your machine from your account, e.g,. git clone ‘https://github.com/yourgithubusername/TrenchR.git’
  • Make sure to track progress upstream by doing git remote add upstream https://github.com/trenchproject/TrenchR.git. Before making changes make sure to pull changes in from upstream by doing either git fetch upstream then merge later or git pull upstream to fetch and merge in one step
  • Make your changes (name your branch something other than ‘main’)
  • If you alter package functionality at all (e.g., the code itself, not just documentation) please do write some tests to cover the new functionality.
  • Push up to your account
  • Submit a pull request to home base at trenchproject/TrenchR
  • Accessing your Githb account through R Studio may be a good option. Available tutorials include this.

Reporting Bugs

This section guides you through submitting a bug report for TrenchR.

How Do I Submit A Bug Report?

Bugs are tracked as GitHub issues.

Explain the problem and include additional details to help maintainers reproduce the problem:

  • Use a clear and descriptive title for the issue to identify the problem.
  • Describe the exact steps which reproduce the problem in as many details as possible.
  • Provide specific examples to demonstrate the steps. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you’re providing snippets in the issue, use Markdown code blocks.
  • Describe the behavior you observed after following the steps and point out what exactly is the problem with that behavior.
  • Explain which behavior you expected to see instead and why.

Include details about your configuration and environment:

  • What’s the name and version of the OS you’re using?

Suggesting Enhancements

This section guides you through submitting an enhancement suggestion for TrenchR, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion 📝 and find related suggestions 🔎.

How Do I Submit A Enhancement Suggestion?

Enhancement suggestions are tracked as GitHub issues. Create an issue on TrenchR repository and provide the following information:

  • Use a clear and descriptive title for the issue to identify the suggestion.
  • Provide a step-by-step description of the suggested enhancement in as many details as possible.
  • Provide specific examples to demonstrate the steps. Include copy/pasteable snippets which you use in those examples, as Markdown code blocks.
  • Describe the current behavior and explain which behavior you expected to see instead and why.
  • Explain why this enhancement would be useful to TrenchR .

Your First Code Contribution

Unsure where to begin contributing to TrenchR? You can start by looking through these beginner and help-wanted issues:

  • [Beginner issues][beginner] - issues which should only require a few lines of code, and a test or two.
  • [Help wanted issues][help-wanted] - issues which should be a bit more involved than beginner issues.

Both issue lists are sorted by total number of comments. While not perfect, number of comments is a reasonable proxy for impact a given change will have.

Additional project information is available on the TrEnCh Project website.

Local development

TrenchR packages can be developed locally. For instructions on how to do this, see the develop section

Pull Requests

  • Fill good amount of detail in the PR
  • Do not include issue numbers in the PR title
  • Follow the R Styleguide
  • Document new code based on the R Styleguide

Styleguides

Git Commit Messages

  • Use the present tense (“Add feature” not “Added feature”)
  • Use the imperative mood (“Move cursor to…” not “Moves cursor to…”)
  • Limit the first line to 72 characters or less
  • Reference issues and pull requests liberally after the first line
  • When only changing documentation, include [ci skip] in the commit title
  • Consider starting the commit message with an applicable emoji:
    • 🎨 :art: when improving the format/structure of the code
    • 🐎 :racehorse: when improving performance
    • 🚱 :non-potable_water: when plugging memory leaks
    • 📝 :memo: when writing docs
    • 🐧 :penguin: when fixing something on Linux
    • 🍎 :apple: when fixing something on macOS
    • 🏁 :checkered_flag: when fixing something on Windows
    • 🐛 :bug: when fixing a bug
    • 🔥 :fire: when removing code or files
    • 💚 :green_heart: when fixing the CI build
    • ✅ :white_check_mark: when adding tests
    • 🔒 :lock: when dealing with security
    • ⬆️ :arrow_up: when upgrading dependencies
    • ⬇️ :arrow_down: when downgrading dependencies
    • 👕 :shirt: when removing linter warnings

R Styleguide

All R code style is borrowed from Hadley Wickham R Pkgs book R packages.

  • Describe the function in detail
  • Refer to any citations, or give credit if part or whole of the function is adapted

R Example

#' Converts angle in radians to degrees
#'
#' @details Converts angles in radians to degrees
#' 
#' @description This function allows you to convert angle in radians to degrees
#' @param rad angle in radians
#' @keywords radians to degrees
#' @return angle in degrees
#' @export
#' @examples
#' \dontrun{
#' radian_to_degree(rad=0.831)
#' }
radian_to_degree <- function(rad) {(rad * 180) / (pi)}

Additional Notes

Issue and Pull Request Labels

This section lists the labels we use to help us track and manage issues and pull requests.

Credit

Contributrion template adapted by referring to Atom and rOpenSci projects.