Contributors and maintainers are expected to abide by the Bioconductor Code of Conduct
This instructions have been adapted from
Following these guidelines will help us to better understand your report, replicate the issues, and track down the source problems.
Please do the following:
Check the GitHub issues for this package
If you find an open issue that describes the same problem, kindly add a comment to let others know that you are experiencing the same issue.
If no open issue already exists for your problem then kindly create a new issue.
Note: If you find a Closed issue that seems 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 the new one.
Bugs are tracked as GitHub issues.
When you are creating a bug report, please do the following:
Explain 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 a specific example. (Includes links to pastebin, gists and so on.) If you’re providing snippets in the issue, use Markdown code blocks.
Describe the behaviour you observed after following the steps
Provide additional context for the problem (some of these may not always apply)
Include details about your configuration and environment
Packages and versions you are using? (see R command sessionInfo())
Name and version of the OS you’re using?
Enhancements include new features as well as minor improvements to existing functionality. Following these suggestions will help maintainers and the community understand your suggestion and find related suggestions.
Enhancement proposals are tracked as GitHub issues.
Explain the enhancement
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.
If you want to change current behaviour…
OPTIONALLY: Include screenshots and animated GIFs.
Provide additional context for the enhancement
Explain why this enhancement would be useful to users and isn’t something that can or should be implemented as a separate package.
Do you know of other projects where this enhancement exists?
Include details about your configuration and environment
Package versions (see R sessionInfo()).
Name and version of the OS
All packages can be developed locally, and contributions suggested via pull requests.
Let’s use a git flow kind of approach. Development version should be done against the master branch and then merged to release for release. (https://guides.github.com/introduction/flow/)
Before you start working on code, it is often a good idea to open an enhancement suggestion
Hit the ‘Fork’ button on the repositories page to create a forked copy of the target package for your own Github account. This will ensure your work and experiments won’t hinder other users of the released and stable package.
From there you can clone your fork of the package and work on it on your machine using git. Here’s an example of cloning, assuming you already forked mia:
Git will download or “clone” your fork and put it in your local folder.
It is beyond the scope of this document to describe good git and github use in more specific detail, as the folks at Git and GitHub have already done that wonderfully on their own sites.
If you have additional questions, see the contact details at microbiome.github.io.
In your code changes
In your pull request
Describe the changes in the pull request
Provide a clear, simple, descriptive title.
Do not include issue numbers in the PR title.
If you have implemented new features or behaviour
If you have changed current behaviour…
You can open a pull request early on and push changes to it until it is ready, or you can do all your editing locally and make a pull request only when it is finished - it is up to you.
When your pull request is ready on Github, mention one of the maintainers of the repo in a comment e.g. @antagomir and ask them to review it. You can also use Github’s review feature. They will review the code and documentation in the pull request, and will assess it.
Your pull request will be accepted and merged if:
It may also be that the reviewers or package maintainers will want to you to make changes to your pull request before they will merge it. Take the time to understand why any such request has been made, and freely discuss it with the reviewers.
: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:green_heart: when fixing the CI build:white_check_mark: when adding tests:arrow_up: when upgrading dependencies:arrow_down: when downgrading dependencies:exclamation: when removing warnings or depreciationsIndent with 4 spaces.
Separate logical blocks of code with one blank line. Although it is common and acceptable for short single-line functions to be defined together on consecutive lines with no blank lines between them.
Function names, apart from constructors, are all camelCase.
Generally try to keep lines below 80-columns, unless splitting a long line onto multiple lines makes it harder to read.
A minimal workflow for package development is as follows.
Fork (with Git) mia R package from [https://github.com/microbiome/mia]
Clone (with Git) your own fork of mia; or if you have cloned it earlier, then make sure that your branch is in sync with the upstream repository (see next section)
Test package (in R): devtools::test() (and fix possible issues)
Test examples: devtools::run_examples()
Update documentation (convert R files to man/ files): devtools::document()
Build package: devtools::build()
Run Bioconductor checks: BiocCheck::BiocCheck() (for more details on Bioconductor formatting guidelines and automated checks, see Bioconductor package guidelines and instructions on Bioconductor packages: Development, Maintenance, and Peer Review)
Load the updated package: devtools::load_all()
Install the package: devtools::install()
Once the package passes all build checks, commit & push to your own fork, then make a pull request (PR) to the original repository. This will trigger additional automated checks. If they fail, inspect the reason, fix accordingly, and update your PR (simply commit + push new material to your fork; the PR is already open).
Final checks after the R tests; run on command line (replace “R” with your custom R path if necessary):
R CMD buildmia/`R CMD check mia_x.y.z.tar.gzR CMD BiocCheck mia_x.y.z.tar.gzR CMD INSTALL mia_x.y.z.tar.gzAfter updating the package, remember to do the following (if applicable):
tests/)vignettes)After accepted pull request, check if further updates are needed in:
Before new pull request, check that your own fork is in sync with the main development version. Command line version goes as follows.
# Add the main repository as your _upstream_
`git remote add upstream git@github.com:microbiome/mia.git`
# Fetch the changes from upstream (main version) and origin (your fork):
git fetch --all
# Merge those changes to your fork:
git merge origin/master
git merge upstream/master
# Finally, commit and push to origin (your version)
# then open a new PR from the Github site if relevant.
git push origin master