Skip to content

Latest commit

 

History

History
115 lines (84 loc) · 8.48 KB

CONTRIBUTING.md

File metadata and controls

115 lines (84 loc) · 8.48 KB
Raw

Contributing

Welcome

Thank you for your interest in contributing to mmrefpoints! We hope to maintain this package as a resource for a broad set of stakeholders and modelers.

Table of Contents

Short Links

How Can I Contribute?

Style Guides

Short Links

  • View the rest of the Ocean Modeling Forum Marine Mammal Bycatch Working Group products here
  • Report bugs here
  • Contact Margaret at margaret (dot) siple (at) noaa.gov

How Can I Contribute?

Style Guides

Reporting Bugs

Bugs are tracked as GitHub issues. If you find a bug, please make your report as detailed as possible. Fill out the required bug report template; the information it asks for helps us resolve issues faster.

Note: If you find a Closed issue that looks like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one (you can tag issues by a hashtag (#) followed by the issue number).

Suggesting Enhancements

📝 We are always interested in how to make this package more useful and accessible. If you have an enhancement to suggest, please submit a Feature Request.

How do I submit a good enhancement suggestion?

Enhancement suggestions are tracked as GitHub issues. Create an issue on the mmrefpoints repository and include the following:

  • 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.
  • Include screenshots and animated GIFs which help you demonstrate the steps or point out the part of Atom which the suggestion is related to. You can use this tool to record GIFs on macOS and Windows, and this tool or this tool on Linux.
  • Explain why this enhancement would be useful to most mmrefpoints users and stakeholders.
  • Specify what version of mmrefpoints you are using and whether you are using the Shiny app in the browser, the local Shiny app within the mmrefpoints package, or the functions in mmrefpoints by themselves.
  • Specify the name and version of the OS you're using.

Pull requests

If you have a code suggestion in hand, please submit a pull request.

Write an issue on GitHub

Git commit messages

(many of these are lifted from the Atom style guide for 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
    • 📝 :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
    • ✅ :white_check_mark: when adding tests
    • ⬆️ :arrow_up: when upgrading dependencies
    • ⬇️ :arrow_down: when downgrading dependencies

Code style guides

We have adapted the following coding style guidelines from simulation developers with established guidelines, like ss3sim.

You will notice that some of the functionality of mmrefpoints may not follow all the advice in this style guide. I am working on streamlining much of this code (especially the Shiny code 👷), so in the meantime we request that you do as we style guide, not as we do.

Coding style

  • Guides
  • Code rules
    • Use vapply or lapply instead of sapply because sapply is not consistent in the what class of object it returns (this may not yet be implemented in the package)
    • Use [ rather than subset because subset will lead to unassigned objects, i.e., R will not know where the column vector name in the subset call comes from
    • Use <- rather than = to assign objects
    • Use seq_len(NROW(x)) or seq_along(x) rather than 1:NROW(x) or 1:length(x) (not yet implemented in the package)
    • Importing functions from other packages in ss3sim functions

Importing functions from other packages

(these guidelines are lifted and adapted from the ss3sim developer wiki, which contains a lot of useful resources for developing code)

What if you need to use a function from another package? Normally you might attach all the functions from a package with a call to library(). This is a bad practice in the context of writing an R package. We shouldn't be attaching other packages in the user's environment. In the context of writing a package we will instead import that function for our use. The package structure ensures that the user has the package installed.

For more details, see http://r-pkgs.had.co.nz/namespace.html

Say you want to use the function mle2 from the bbmle package.

Here are the steps to use the function within your package:

  • Add the package to the list of Imports in the DESCRIPTION file. If it's possible that functionality has changed in the past for the function then specify a >= version number for the package. You can find the version you have installed in many ways. One way is to type help(package = "bbmle") within R. You can also look at your sessionInfo() in R.
  • In the function Rogxyen documentation include @importFrom bbmle mle2. If there are multiple functions to import than list them as @importFrom packagename function1 function2 etc.
  • Call the function as you would normally, e.g., mle2(x, ...)

The above steps outline one of two preferred notations. Within mmrefpoints we also use the :: notation to be explicit about what package a function comes from. E.g., shiny.i18n::update_lang() clearly tells readers of the code that the update_lang() function comes from the shiny.i18n package without readers having to navigate to the top of the code to read the roxygen documentation. This notation also requires that packages be listed in the Imports section of the DESCRIPTION file. We support either notation, but we have largely switched to this one as time goes on.

Occasionally your code might call so many functions from another package that you just want all the functions available. In that case use @import bbmle at the top. I have done this in places in mmrefpoints. But, it is best practices to import specific functions that we need because it saves time, which users appreciate. It also makes the code more explicit.

Code of conduct

Contributors to mmrefpoints follow the Contributor Covenant code of conduct. For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq.