diff --git a/.Rbuildignore b/.Rbuildignore index ca9b67a..e4f720e 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -7,3 +7,4 @@ ^\.github$ ^_pkgdown\.yaml$ ^rbibtools\.Rproj$ +^CONTRIBUTING\.md$ diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..128066b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,28 @@ +--- +name: Bug report +about: Standard bug report template +title: '' +labels: 'bug' +--- + +**Bug description** + +A clear and concise description of what the bug is. + + +**Reproducible example** + +It is easier for developers to help if they can reproduce the problem. +Could you please provide a minimal reproducible example? + + +**Additional context** + +Add any other context about the problem here. + + +
+```r +# Output of sessionInfo() +``` +
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..aa6bc66 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,10 @@ +--- +name: Feature request +about: Standard feature request template +title: '' +labels: 'enhancement' +--- + +**Feature description** + +A clear and complete description of what the requested feature is. diff --git a/.github/ISSUE_TEMPLATE/other_issue.md b/.github/ISSUE_TEMPLATE/other_issue.md new file mode 100644 index 0000000..fd9440d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/other_issue.md @@ -0,0 +1,6 @@ +--- +name: Other issue +about: Template for other issue types +title: '' +labels: '' +--- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..5df80a9 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,271 @@ +# Contributing to rbibtools + +First off, thanks for taking the time to contribute to `rbibtools`! + +All types of contributions are encouraged and valued. See the +[Table of contents](#table-of-contents) for different ways to help and details +about how this project handles them. Please make sure to read the relevant +section before making your contribution. It will make it a lot easier for us +maintainers and smooth out the experience for all involved. + + + +## Table of contents + +- [Code of conduct](#code-of-conduct) +- [Style guide](#style-guide) +- [Commit messages](#commit-messages) +- [Asking questions](#asking-questions) +- [Reporting bugs](#reporting-bugs) +- [Requesting features](#requesting-features) +- [Contributing code](#contributing-code) + + + +## Code of conduct + +This project is released with a +[Contributor Code of Conduct](https://github.com/frbcesab/rbibtools/blob/main/CODE_OF_CONDUCT.md). +By participating, you are expected to uphold this code. Please report +unacceptable behavior to . + + + +## Style guide + +We use the [Tidyverse style guide](https://style.tidyverse.org/) for writing R +code. Functions are documented with the +[roxygen2](https://roxygen2.r-lib.org/articles/roxygen2.html) syntax. +`rbibtools` uses the `lower_snake_case`. + + + +## Commit messages + +If you want to contribute by commiting changes, please try to use the +[Conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) +specification. + + + +## Asking questions + +Before you ask a question, it is best to search for existing +[Issues](https://github.com/frbcesab/rbibtools/issues) that might help +you. In case you have found a suitable issue and still need clarification, you +can write your question in this issue. + +If you then still feel the need to ask a question and need clarification, we +recommend the following: + +- Open a new [Issue](https://github.com/frbcesab/rbibtools/issues/new). +- Use the template [other_issue.md](https://github.com/frbcesab/rbibtools/blob/main/.github/ISSUE_TEMPLATE/other_issue.md). +- Provide as much context as you can about what you're running into. +- Provide project and platform versions (paste the output of `sessionInfo()`). + +We will then take care of the issue as soon as possible. + + + +## Reporting bugs + + + +### Before submitting a bug report + +A good bug report shouldn't leave others needing to chase you up for more +information. Therefore, we ask you to investigate carefully, collect information +and describe the issue in detail in your report. Please complete the following +steps in advance to help us fix any potential bug as fast as possible. + +- Make sure that you are using the latest version of `rbibtools`. +- Determine if your bug is really a bug and not an error on your side. +- To see if other users have experienced (and potentially already solved) the +same issue you are having, check if there is not already a bug report existing +for your bug or error in the [bug tracker](https://github.com/frbcesab/rbibtools/issues?q=label%3Abug). + + + +### How do I submit a bug report? + +We use [GitHub Issues](https://github.com/frbcesab/rbibtools/issues) to +track bugs and errors. If you run into an issue with the project: + +- Open a new [Issue](https://github.com/frbcesab/rbibtools/issues/new). +- Use the template [bug_report.md](https://github.com/frbcesab/rbibtools/blob/main/.github/ISSUE_TEMPLATE/bug_report.md). +- Explain the behavior you would expect and the actual behavior. +- Please provide as much context as possible and describe the +*reproduction steps* that someone else can follow to recreate the issue on +their own. This usually includes your code with a reproducible example. + +We will then take care of the issue as soon as possible. + + + +## Requesting features + + + +### Before requesting a feature + +- Make sure that you are using the latest version of `rbibtools`. +- Read the [documentation](https://github.com/frbcesab/rbibtools/) +carefully and find out if the functionality is already covered. +- Perform a [search](https://github.com/frbcesab/rbibtools/issues) to +see if this enhancement has already been suggested. If it has, add a comment to +the existing issue instead of opening a new one. + + + +### How do I submit a feature request? + +Feature requests are tracked as +[GitHub Issues](https://github.com/frbcesab/rbibtools/issues). + +- Open a new [Issue](https://github.com/frbcesab/rbibtools/issues/new). +- Use the template [feature_request.md](https://github.com/frbcesab/rbibtools/blob/main/.github/ISSUE_TEMPLATE/feature_request.md). +- Provide 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. +- Explain why this enhancement would be useful to most `rbibtools` users. + +We will then take care of the issue as soon as possible. + + + +## Contributing code + + + +### General workflow + +We use the [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow) +to collaborate on this project: + + +1. [Fork](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) +this repository using the GitHub interface. +1. [Clone](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) +your fork using `git clone fork-url` (replace `fork-url` by the URL of your fork). +Alternatively, open RStudio IDE and create a New Project from Version Control. +1. Create a new branch w/ `git checkout -b branch-name` (replace `branch-name` +by the name of your new branch). +1. Make your contribution (see below for examples). +1. Stage (`git add`) and commit (`git commit`) your changes as often as necessary +1. Push your changes to GitHub w/ `git push origin branch-name`. +3. Submit a [Pull Request](https://docs.github.com/en/get-started/quickstart/contributing-to-projects#making-a-pull-request) on the [original repo](https://github.com/frbcesab/rbibtools/compare). + +We will then review the PR as soon as possible. + + + +### Improve documentation + + + +#### Editing the README + +If you want to contribute by improving the README, please edit the `README.Rmd` +(not the `README.md`). Do not forget to update the `README.md` by running: + +```r +rmarkdown::render("README.Rmd") +``` + + + +#### Editing vignettes + +If you want to contribute by editing an existing vignette, just edit the +corresponding `Rmd` file stored in the `vignettes/` folder. + +If you want to contribute by adding a new vignette, create a new `Rmd` file in +the `vignettes/` folder and add the following header: + +```yaml +--- +title: "Vignette Title" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{Vignette Title} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- +``` + +If you use a new external dependency, do not forget to add it in the `DESCRIPTION` +file under the section `Suggests` (only if this package is not already listed +under the section `Imports`). + +Check the integrity of the package with: + +```r +devtools::check() +``` + + + +#### Editing function documentation + +If you want to contribute by improving the documentation of a function, open +the corresponding file in the `R/` folder and edit lines starting with `#'` +([roxygen2](https://roxygen2.r-lib.org/articles/roxygen2.html) syntax). + +Update the documentation (`Rd` files in the `man/` folder) by running: + +```r +devtools::document() +``` + +If you use a new external dependency in the example section, do not forget to +add it in the `DESCRIPTION` file under the section `Imports` (only if this +package is not already listed). + +Check the integrity of the package with: + +```r +devtools::check() +``` + + + +### Fix bug + +If you want to contribute by improving the code of a function, open and edit +the corresponding file in the `R/` folder. + +Check the integrity of the package with: + +```r +devtools::check() +``` + +Do not forget to adapt the +[unit tests](https://r-pkgs.org/testing-basics.html#introducing-testthat) for +the function by editing the corresponding file stored in the `tests/testthat/` +folder. We use the package [`testthat`](https://testthat.r-lib.org/) to +implement unit tests. + +Check your tests by running: + +```r +devtools::test() +``` + + + +### New feature + +If you want to contribute by submitting a new feature, please follow this +workflow: + +1. Create a new `R` file in the folder `R/`. +2. Implement the code of the function. +3. Document your function w/ the [roxygen2](https://roxygen2.r-lib.org/articles/roxygen2.html) syntax. +4. If necessary, add additional dependencies in the `DESCRIPTION` file. +5. Update the package documentation w/ `devtools::document()`. +6. Create a new `R` file in the folder `tests/testthat/`. +7. Implement [unit tests](https://r-pkgs.org/testing-basics.html#introducing-testthat) for the new function. +8. Check the integrity of the package w/ `devtools::check()`. + +**Thanks for your contribution!** diff --git a/DESCRIPTION b/DESCRIPTION index 9961cae..ccd839f 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,12 +1,12 @@ Package: rbibtools Type: Package -Title: Toolbox to Handle bib Files +Title: Toolbox to Handle BibTeX Files Version: 0.0.1 Authors@R: c( person(given = "Nicolas", family = "Casajus", role = c("aut", "cre", "cph"), - email = "nicolas.casajus@fondationbiodiversite.fr", + email = "rdev.nc@gmail.com", comment = c(ORCID = "0000-0002-5537-5294"))) Description: Imports, cleans, and exports BibTeX references exported by references management softwares (e.g. Mendeley, Zotero). @@ -16,12 +16,11 @@ License: GPL (>= 2) Encoding: UTF-8 LazyData: true Roxygen: list(markdown = TRUE) -RoxygenNote: 7.2.1 +RoxygenNote: 7.3.2 Imports: bib2df, stringi Suggests: knitr, - rmarkdown, - writexl + rmarkdown VignetteBuilder: knitr diff --git a/README.Rmd b/README.Rmd index 33b7d8e..b17300a 100644 --- a/README.Rmd +++ b/README.Rmd @@ -21,15 +21,26 @@ rbibtools + • Overview
+ • Installation
+ • Get started
+ • Citation
+ • Contributing +

+ + + +## Overview + +The R package `rbibtools` has been developed to import, clean, and export `.bib` files ([BibTeX](https://www.bibtex.com/) references) exported by common references management software (e.g. Mendeley, Zotero). @@ -52,7 +63,7 @@ library("rbibtools") -## Overview +## Get started The main functions of `rbibtools` are `read_bib()` and `write_bib()`. See the [Get started](https://frbcesab.github.io/rbibtools/articles/rbibtools.html) vignette for an overview of the package. @@ -63,13 +74,16 @@ overview of the package. Please cite this package as: -> Casajus Nicolas (`r format(Sys.Date(), "%Y")`) rbibtools: A Toolbox to handle -bib files. R package version 0.0.1. +> Casajus Nicolas (`r format(Sys.Date(), "%Y")`) rbibtools: A toolbox to handle +BibTeX files. R package version 0.0.1. + +## Contributing -## Code of Conduct +All types of contributions are encouraged and valued. For more information, +check out our [Contributor Guidelines](https://github.com/FRBCesab/rbibtools/blob/main/CONTRIBUTING.md). Please note that the `rbibtools` project is released with a -[Contributor Code of Conduct](https://contributor-covenant.org/version/2/0/CODE_OF_CONDUCT.html). +[Contributor Code of Conduct](https://contributor-covenant.org/version/2/1/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms. diff --git a/README.md b/README.md index 87d7f27..0ae03e8 100644 --- a/README.md +++ b/README.md @@ -7,20 +7,27 @@ [![R CMD Check](https://github.com/frbcesab/rbibtools/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/frbcesab/rbibtools/actions/workflows/R-CMD-check.yaml) -[![Website -deployment](https://github.com/frbcesab/rbibtools/actions/workflows/pkgdown.yaml/badge.svg)](https://github.com/frbcesab/rbibtools/actions/workflows/pkgdown.yaml) -[![CRAN -status](https://www.r-pkg.org/badges/version/rbibtools)](https://CRAN.R-project.org/package=rbibtools) +[![Website](https://github.com/frbcesab/rbibtools/actions/workflows/pkgdown.yaml/badge.svg)](https://github.com/frbcesab/rbibtools/actions/workflows/pkgdown.yaml) [![License: GPL (\>= 2)](https://img.shields.io/badge/License-GPL%20%28%3E%3D%202%29-blue.svg)](https://choosealicense.com/licenses/gpl-2.0/) -[![LifeCycle](https://img.shields.io/badge/lifecycle-experimental-orange)](https://lifecycle.r-lib.org/articles/stages.html#experimental) -[![Project Status: -Active](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) -The R package `rbibtools` imports, cleans, and exports `.bib` files -([BibTeX](https://www.bibtex.com/) references) exported by common -references management software (e.g. Mendeley, Zotero). +## Table of contents + +

+• Overview
• +Installation
• +Get started
• +Citation
• +Contributing +

+ +## Overview + +The R package `rbibtools` has been developed to import, clean, and +export `.bib` files ([BibTeX](https://www.bibtex.com/) references) +exported by common references management software (e.g. Mendeley, +Zotero). ## Installation @@ -38,7 +45,7 @@ Then you can attach the package `rbibtools`: library("rbibtools") ``` -## Overview +## Get started The main functions of `rbibtools` are `read_bib()` and `write_bib()`. See the [Get @@ -49,12 +56,16 @@ vignette for an overview of the package. Please cite this package as: -> Casajus Nicolas (2022) rbibtools: A Toolbox to handle bib files. R -> package version 0.0.1. +> Casajus Nicolas (2024) rbibtools: A toolbox to handle BibTeX files. R +> package version 0.0.1. + +## Contributing -## Code of Conduct +All types of contributions are encouraged and valued. For more +information, check out our [Contributor +Guidelines](https://github.com/FRBCesab/rbibtools/blob/main/CONTRIBUTING.md). Please note that the `rbibtools` project is released with a [Contributor Code of -Conduct](https://contributor-covenant.org/version/2/0/CODE_OF_CONDUCT.html). +Conduct](https://contributor-covenant.org/version/2/1/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms. diff --git a/man/rbibtools-package.Rd b/man/rbibtools-package.Rd index 8384263..0d54182 100644 --- a/man/rbibtools-package.Rd +++ b/man/rbibtools-package.Rd @@ -4,9 +4,9 @@ \name{rbibtools-package} \alias{rbibtools} \alias{rbibtools-package} -\title{rbibtools: Toolbox to Handle bib Files} +\title{rbibtools: Toolbox to Handle BibTeX Files} \description{ -Imports, cleans, and handles BibTeX references exported by references management softwares (e.g. Mendeley, Zotero). +Imports, cleans, and exports BibTeX references exported by references management softwares (e.g. Mendeley, Zotero). } \seealso{ Useful links: @@ -17,7 +17,7 @@ Useful links: } \author{ -\strong{Maintainer}: Nicolas Casajus \email{nicolas.casajus@fondationbiodiversite.fr} (\href{https://orcid.org/0000-0002-5537-5294}{ORCID}) [copyright holder] +\strong{Maintainer}: Nicolas Casajus \email{rdev.nc@gmail.com} (\href{https://orcid.org/0000-0002-5537-5294}{ORCID}) [copyright holder] } \keyword{internal}