contribute.RmdThere are many ways to contribute to our project.
Status to
Todo, Last Modified to today, and change
Assigned to your GitHub username.Note that it’s best to work on vignettes from packages passing the Bioconductor build report on devel. Specifically, the build status should be ‘OK’ or ‘WARNING’. Attempting to convert vignettes belonging to packages that are not passing may make it difficult to run the vignette and verify that it as well as the package are working correctly.
If a package is not maintained by Bioconductor, the maintainer must be contacted to confirm if they will accept a pull request.
If the package’s URL on the landing page is to the package’s GitHub mirror, you can make initial contact by creating an issue. It’s sometimes worth trying to search GitHub for a mirror even if none is listed.
If no mirror exists, you should contact the maintainer by email; however, you may need to also recommend that they create a mirror of their package’s Bioconductor repository.
```
Hi Maintainers_Name,
I'm a [Sweave2Rmd](https://github.com/Bioconductor/sweave2rmd) volunteer and
we're trying to replace Bioconductor Sweave vignettes with R Markdown. R
Markdown vignettes convert to HTML, use BiocStyle, and are easier
to maintain.
Would you consider accepting a pull request for the R Markdown version of
__vignette_name__ for __package__ from one of our volunteers?
We'll ask you to review and accept the pull request. You'll also need to
bump the version number in your DESCRIPTION file so that the Bioconductor
build machines will recognize that a new version is available.
We send pull requests through GitHub; however, we noticed that your package
does not have a GitHub repository. We hope you'll [consider creating
repository for your package in
GitHub](https://contributions.bioconductor.org/git-version-control.html#maintain-github-bioc).
Some benefits of a GitHub repository includes:
* Collaboration: GitHub provides a platform for collaboration, including issue tracking and pull requests.
* Community Engagement: GitHub fosters community involvement, allowing discussions and contributions.
Thank you for your time. I look forward to your response.
Best regards,
[Your Name]
Volunteer, Sweave2Rmd Project
```Search for the package on BiocViews.
Click on the package name to go to the package’s landing page.
Under Details, find the URL to the
package’s repository.
Open an issue asking if they would accept a pull request with the converted vignette. You can modify the following example to post on the issue.
Hi,
I'm a [Sweave2Rmd](https://github.com/Bioconductor/sweave2rmd) volunteer
and we're trying to replace Bioconductor Sweave vignettes with R Markdown.
R Markdown vignettes convert to HTML, use BiocStyle, and are easier to
maintain.
Would you consider accepting a pull request for the R Markdown version of
__vignette_name__ from one of our volunteers?
We'll ask you to review and accept the pull request. You'll also need to
bump the version number in your DESCRIPTION file so that the Bioconductor
build machines will recognize that a new version is available.
Thanks for your time.Note: If the package has multiple vignettes, you can modify the communication as follows
Would you consider accepting pull requests for R Markdown versions of the
following vignettes:
* packageName/vignettes/packageName.Rnw
* packageName/vignettes/packageName2.RnwSometimes maintainers deprecate vignettes so they may only want some files converted.
Search for the package on BiocViews.
Click on the package name to go to the package’s landing page.
Find the maintainer’s email.
Email the maintainer asking if they would accept a pull request with the converted vignette. You can modify the following example email to send to the maintainer:
Hi,
I'm a [Sweave2Rmd](https://github.com/Bioconductor/sweave2rmd) volunteer
and we're trying to replace Bioconductor Sweave vignettes with R Markdown.
R Markdown vignettes convert to HTML, use BiocStyle, and are easier to
maintain.
Would you consider accepting a pull request for the R Markdown version of
__vignette_name__ for __package__ from one of our volunteers?
We'll ask you to review and accept the pull request. You'll also need to
bump the version number in your DESCRIPTION file so that the Bioconductor
build machines will recognize that a new version is available.
Thanks for your time.As above, you can alter the content if there are multiple vignettes.
Verify the vignette isn’t already on the board. If the vignette must be added, include the path to the vignette as the title and set the Status.
After you contact the maintainer, set the Status to
Contacted and Last Modified to today.
Once you hear back from the maintainer, if they will accept the pull
request, set the Status to Todo for each
vignette. Similarly, if they will not accept a pull request, set it to
Maintainer Not Interested. If after two weeks, the
maintainer is not responsive, set the Status to
Unresponsive and update Last Modified to
today’s date.
Note: We use file to indicate the name of the Sweave
file that we will replace with an .Rmd file.
On the project board, select a vignette and set the
Status to In Progress. Also, write your GitHub
username under Assigned and set Last Modified
to today.
Search for the package on BiocViews.
Click on the package to visit its landing page.
Under Documentation, find PDF of the vignette you
selected in step 1. You can see the name of the PDF by inspecting its
URL. Use the content of the PDF as your guide when you create the R
Markdown file. The content of the HTML generated by knitting the R
Markdown file should closely match the contents of the PDF.
Under Details, find the URL to the
repository.
Fork the repository you will work on.
Make a branch for your changes:
git switch -c file-Rmd
If BiocStyle and knitr aren’t in the
DESCRIPTION file, add them under Suggests.`
Add VignetteBuilder: knitr as a new line in the
DESCRIPTION file.
If agreed with the maintainer, add yourself as a contributor. In the DESCRIPTION file, convert the Authors section to conform to the following block.
Authors@R: c(
person("First Name", "Last Name", role = "aut"),
person("First Name", "Last Name", role = "ctb"),
person("Your First Name", "Your Last Name", role = "ctb",
comment = "Converted YOUR_VIGNETTE_NAME vignette from Sweave to RMarkdown / HTML."),
person("Bioconductor Package Maintainer",
email = "maintainer@bioconductor.org", role = "cre"))Note: After performing the conversion, if you have contributed to multiple conversions, you can shorten the contributor comment in the DESCRIPTION file to:
comment = "Converted vignettes from Sweave to RMarkdown / HTML."The following roles indicate the following
Note: that the Maintainer in this case is
Bioconductor Package Maintainer. The separate maintainer
line has been deleted and moved into the Authors@R. If you
don’t remove the separate maintainer line, the package will fail to pass
on the build report.
Commit your changes to your branch. Write a brief and precise commit message, such as
# Add changes to the file to the commit
git add DESCRIPTION
# Create commit with the following message
git commit -m 'Update DESCRIPTION with BiocStyle, knitr, VignetteBuilder'If you have pandoc and Rnw2Rmd
installed, you can utilize them for preprocessing your documents. Follow
the steps below:
Check if the Rnw2Rmd package is already installed by
running the following command in the R console:
library(Rnw2Rmd)If the console indicates that the Rnw2Rmd package is missing, install it using the following commands:
if (!require("BiocManager", quietly = TRUE))
install.packages("BiocManager")
BiocManager::install("Bioconductor/Rnw2Rmd")Once the package is successfully installed, you can use it to perform the conversion by executing this command in the R console:
Rnw2Rmd(from = "Filepath.Rnw", to = "Filepath.Rmd", validate = FALSE)Make sure to replace Filepath with the actual paths to your
.Rnw and .Rmd files respectively.
Note: Occasionally Rnw2Rmd has some` issues processing,
so we’ll have to manually correct these sections of the .Rmd file. You
can refer to converting the code chunks
manually below.
Steps for converting the code chunks manually:
Modify code chunk syntax: In R Markdown, code chunks are denoted
by three backticks followed by the curly braces with the language name
(e.g., {r}). Replace the Sweave code chunk syntax
(<<>>=) with the R Markdown code chunk syntax.
Adjust code chunk options: Adjust any code chunk options if necessary. In R Markdown, code chunk options are specified within the curly braces following the language name. For example, if you have a Sweave code chunk like <<chunkname, echo=FALSE>>=, you would change it to {r chunkname, echo=FALSE} in R Markdown.
For more clarity you can see the example of code chunk below
# sweave code chunk example in .Rnw file the code block end with @ sign
<<stream, eval=FALSE>>=
strm <- FastqStreamer("a.fastq.gz")
repeat {
fq <- yield(strm)
if (length(fq) == 0)
break
## process chunk
}
@# Converted R Markdown code chunk in .Rmd file
```{r stream, eval=FALSE}
strm <- FastqStreamer("a.fastq.gz")
repeat {
fq <- yield(strm)
if (length(fq) == 0)
break
## process chunk
}
```Knit the R Markdown vignette: Once you have converted the content and added R Markdown formatting, you can knit the R Markdown vignette to generate the output document. RStudio provides a “Knit” button for this purpose.
Review and refine: Review the generated output document, make any necessary refinements, and repeat the process until you are satisfied with the converted R Markdown vignette.
If the file doesn’t have yaml at the top, add it using the following as an example:
---
title: "Vignette Title"
author: Vignette Author
date: August 15, 2023
package: PackageName
vignette: >
%\VignetteIndexEntry{Vignette Title}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
output:
BiocStyle::html_document
---If the document will need a table of contents, you can alter the
output as follows:
output:
BiocStyle::html_documents
number_sections: true
toc: true
toc_depth: 4Note: Where the date is shown, you want to put the following inline code surrounded by backticks, so that it will be updated whenever the vignette is compiled:
r format(Sys.Date(), "%B %d, %Y")If agreed with the maintainer, add yourself as a contributor:
---
title: "Vignette Title"
author:
- name: Vignette Author
affiliation: Vignette Author's Institution
- name: Your Name
affiliation: "Vignette translation from Sweave to R Markdown / HTML"
date: August 15, 2023
package: PackageName
vignette: >
%\VignetteIndexEntry{Vignette Title}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
output:
BiocStyle::html_document
---Note: Using affiliation to give attribution is a hack;
however, when you knit the .Rmd, it will display your name and only the
value of affiliation.
If using RStudio, Knit your new vignette and compare
with the Sweave version periodically to ensure that the HTML produced
from your R Markdown file is representative of the PDF you found in step
4.
Repeat 16-17 until your new HTML vignettes
accurately represents the Sweave version. Note: If you get stuck or run
into an error, ask for help on the #sweave2rmd channel on the Bioconductor Community
Slack. Provide any helpful information, including error messages,
the vignette and the package you’re working on.
Add and commit your changes to your branch
git add file.Rmd
git commit -m 'Convert file to Rmd'Remove the Sweave file with git rm file.Rnw and
commit the change with
git commit -m 'Remove file.Rnw'.
Push your
branch back to GitHub with
git push origin file-rmd.
On github.com, go to your forked repository and create a pull request.
In the comments of the pull request, ask for a review from
@Bioconductor/sweave2rmd and attach the PDF and HTML
vignettes. If you opened an issue to communicate with the maintainer,
you can automatically link the pull request and the set the issue to be
closed upon merge by add the word “close” and the number of the issue in
the comments–e.g., close #192 to close issue #192.
On the project board, set the Status to
PR Needs Review and update
Last Modified.
Give us time to review your pull request.
If your reviewer or the maintainer leaves any comments, address them until your pull request is ready to merge. Repeating 14-17 and 19 as necessary.
When reviewing a pull request, confirm
the .Rmd file knits to HTML Note: The
best way to check is to R CMD build the package then check
for the html in the tarball. This is how it is built on the Bioconductor
build system. If you only knit the file, RStudio’s knitter will knit
regardless of errors in the DESCRIPTION file.
For example, where the package is GenomicAlignments and
the vignette is WorkingWithAlignedNucleotides.Rmd:
$ # Build the package
$ R CMD build GenomicAlignments
* checking for file ‘GenomicAlignments/DESCRIPTION’ ... OK
* preparing ‘GenomicAlignments’:
* checking DESCRIPTION meta-information ... OK
* cleaning src
* installing the package to build vignettes
* creating vignettes ... OK
* cleaning src
* checking for LF line-endings in source and make files and shell scripts
* checking for empty or unneeded directories
* building ‘GenomicAlignments_1.33.1.tar.gz’
$ # Check the tarball for the html
$ tar ztf GenomicAlignments_1.33.1.tar.gz | grep 'doc/WorkingWithAlignedNucleotides'
GenomicAlignments/inst/doc/WorkingWithAlignedNucleotides.R
GenomicAlignments/inst/doc/WorkingWithAlignedNucleotides.Rmd
GenomicAlignments/inst/doc/WorkingWithAlignedNucleotides.htmlthe .Rnw file has been removed
in the DESCRIPTION file
BiocStyle and knitr are included in
Suggests
VignetteBuilder: knitr existsif agreed with the Maintainer,
.Rmd file, the contributor is in the Author list
in the yaml. They can be added with the affliation hack to
specify that they performed the conversion from Sweave to R
Markdown.DESCRIPTION file, the contributor is in
Authors@R with role="ctb" and a
comment that they converted or translated the Sweave
document to R Markdown. If the contributor converted more than one, the
comment can be generalized to reduce the listing of separate vignettes.
For example,
person("First Name", "Last Name", role="ctb", comment="'Title' vignette translation from Sweave to Rmarkdown / HTML")
and
person("First Name", "Last Name", role="ctb", comment="Vignette translations from Sweave to Rmarkdown / HTML").Author and Maintainer lines into the
Authors@R vector, check that the Authors@R
vector includes the maintainer as specified with
role='cre'. Note: the separate Maintainer line
should be completely removed.the HTML document is representative of the
PDF in content and in general the presentation
the R Markdown file is representative of the Sweave document and
follows best practices, such as replacing links to Bioconductor packages
with calls to BiocStyle’s Biocpkg()
Following Bioconductor
Packages: Development, Maintenance, and Peer Review the package
passes R CMD build and R CMD check with no
errors
Only files necessary for the conversion are included in the pull request. See the Bioconductor Packages: Development, Maintenance, and Peer Review for more information.
Code blocks are surrounded by a blank line, and there are no blank lines before the start or after the end of the code within the code block.
For example, you can see the formatting of code blocks below:
# Examples of Code Blocks Formatting
You can see here in this example that we have a single blank line before and after
every code chunk, section, or paragraph. Also, you will notice that there are no
blank lines before the start or after the end of the code within the code block.
```{r quick_start-load, results="hide", message=FALSE}
library(GenomicFiles)
```
Ranges can be a `GRanges`, `GRangesList` or `GenomicFiles` class.
```{r quick_start-ranges}
gr <- GRanges("chr14", IRanges(c(19411500 + (1:5)*20), width=10))
```Long lines have been broken up and reformatted, you can achieve
this by selecting the text in your script and then clicking on
Code > Reflow Comment in R Studio. It will automatically
reformat your script and text
Here’s a checklist you can use with the pull request:
- [ ] the `.Rmd` file knits to `HTML`
- [ ] `R CMD build` runs without errors or timeouts
- [ ] the tarball from `R CMD build` contains the `HTML` (check with the
following by substituting the package name and vignette name `tar ztf
package_name.tar.gz | grep 'doc/vignette_name'`)
- [ ] the `.Rnw` file has been removed
- In the `DESCRIPTION` file
- [ ] `BiocStyle` and `knitr` are listed in `Suggests`
- [ ] the line `VignetteBuilder: knitr` exists
- [ ] any added lines use the same spacing and indents as the existing document
- If agreed with the Maintainer
- [ ] the contributor is in the author list in the `DESCRIPTION` file*.
- [ ] the contributor is in the author list in the vignette's YAML*.
- If this pull request involves converting from separate `Author` and `Maintainer`
lines to the `Authors@R` vector, please ensure that
- [ ] the `Authors@R` vector includes the maintainer as specified with `role='cre'`.
- [ ] the `Maintainer` line is completely removed.
- [ ] `HTML` document is representative of the `PDF` in content and
in general the presentation
- [ ] Where the contributor was not able to preserve the content and presentation
of the `PDF` is noted as a comment in the pull request
- [ ] the R Markdown file is representative of the Sweave document and follows
best practices, such as replacing links to Bioconductor packages with calls
to BiocStyle's `Biocpkg()`
- [ ] Only files necessary for the conversion are included in the pull request.
- [ ] Long lines have been broken up and reformatted, you can achieve this by
selecting the text in your script and then clicking on `Code > Reflow Comment`
in R Studio.
- [ ] Code blocks are surrounded by a blank line, and there are no blank lines
before the start or after the end of the code within the code block.
* Refer to the contribution guide for acceptable formatsUse the comments to communicate issues to resolve for the volunteer who made the pull request.
When all issues are resolved, ask the maintainer to approve the pull
request and remind them to bump the version in the
DESCRIPTION file and push to Bioconductor.