initial structure

_quarto.yml

@@ -2,12 +2,33 @@ project:
   type: book
 
 book:
-  title: "Packages in the omopverse"
+  title: "Building tidy R packages for the OMOP common data model"
   author: "Edward Burn, Martí Català"
   date: today
   chapters:
   - index.qmd
-  - principles.qmd
+  - part: part_one.qmd
+    chapters:
+    - principles.qmd
+    - omop_packages.qmd
+    - function_interfaces.qmd
+    - function_outputs.qmd
+    - contributing.qmd
+  - part: part_two.qmd
+    chapters:
+    - documenting_functions.qmd
+    - readme.qmd
+    - vignettes.qmd
+  - part: part_three.qmd
+    chapters:
+    - unit_testing.qmd
+  - part: part_four.qmd
+    chapters:
+    - input_validation.qmd
+    - optimising_code.qmd
+  - part: part_five.qmd
+    chapters:
+    - releasing.qmd
 
 bibliography: references.bib
 

contributing.qmd

@@ -0,0 +1,96 @@
+# Contributing to a package
+
+## GitHub issues
+
+### Opening GitHub issues
+
+The first step to contributing to an existing package is by opening issues on its GitHub repository. These issues could be about bugs you encountered when using the package, requests for additional functionality (that you might even want to add yourself), or clarification questions on package documentation.
+
+### What makes a good issue
+If reporting a bug, then a [reprex](https://reprex.tidyverse.org/) makes the maintainers life much, much easier (and in turn increases the likelihood of a quick fix being introduced much higher!). This reprex will allow the developer to quickly reproduce the issue. This is already halfway to solving it, given the old adage
+> "A problem well stated is half solved."
+ 
+Often an issue may arise when running code against a database with real patient-level data which can make it challenging to quickly create a reprex (as the patient data for which the bug was seen cannot be shared). In this situation it may be possible to reproduce the problem on an available synthetic dataset like Eunomia, in which case the package developer will be able to reproduce the bug with the synthetic data. However, it may be that you only encounter the issue for some particular set of patients with specific characteristics which are not seen in the synthetic data. In this case you can, for example, use the omock package to create a set of synthetic patients with these characteristics so that the developer can use this same data to reproduce the problem.
+
+Although of course it would be ideal to include a reprex, this may not always be possible. In such cases please do make sure to provide a bug report, with as much information as possible, as this will still be extremely useful and appreciated.
+
+If opening an issue to ask for clarifications on documentation or with requests for additional functionality, the more precise and specific the issue the better. If you have a long laundry list of feature requests, it would generally be better to open each as separate issues so they can be addressed incrementally.
+
+Note, even if you are not the maintainer of package but want to open a pull request to change documentation or add functionality then try to always open an issue to discuss this first. Even some seemingly trivial changes might be out of scope for the package (or they might have already been added in development branches of the repo). However well-intentioned, "drive-by pull requests" are often challenging for package maintainers to deal with.
+
+
+## Responding to GitHub issues
+
+On the other side of the equation if you are the maintainer of package, receiving issues is one the main ways you will receive feedback on the package. Get used to starting with somewhat vague issues that will need some back and forth to get to the route of the problem or request for additional functionality. 
+
+When a bug is fixed in the package as a rule you should also add a corresponding test to make sure that it will stay fixed into the future. One benefit of being given a reprex is that not only will it help you to fix the problem but the reprex itself can be used as the test for the package. By receiving and acting on issues raised, which will often be somewhat exotic edge cases or people using the package in some way that you hadn't expected, the package will become hardened over time. 
+
+When it comes to requests for adding functionality, or even offers to add it, this is a tricky balancing act. Remember that you will be the one maintaining the package in the long-term. It is often the case that the quick addition of something seemingly useful can make a package more difficult to maintain or extend in the future. Typically it is worth waiting a day or two at least before agreeing to add something to a package so that you don't rush into making an addition or change that you will later come to regret.
+
+Another point to keep in mind when considering issues with requests for functionality is whether to add more general functionality than is being asked for. A well-intentioned user may be asking for something very specific to be added, but often underlying this request will be a broader need for more general functionality. This my tie in to other requests received, or may even need more discussion with users to better understand whether there is a broader need at play.
+general solutions
+
+Remember that sadly few people be opening issues with praise if they've used your package successfully. The majority of users will use the code you've written without a problem and likely without even realising how much work has gone into it. And the people that do open issues are providing an extemely valuable service that will lead to the software getting better and better over time. So try to keep this in mind when tackling the seemingly never-ending list of issues you'll get if your software is being used.  
+
+## Contributing code or documentation
+
+Contributing documentation is one of the best ways to improve a package. Fixing typos, adding clarifications, and even writing whole vignettes will almost always be highly welcomed by the maintainer and improve the experience of other users. 
+
+Contributing code is a more involved task. Before starting, make sure you've at the very least interacted with the maintainer so that they will be in favour of the changes or additions you are planning. 
+If fixing a bug, make sure to add tests alongside code changes to show that it is truly fixed. When fixing a bug existing tests should typically be unchanged (unless there is an issue with the test itself). If you are having to change existing tests to fix a bug this is normally a sign that there might be some more profound issue and will likely need back and forth between you and the maintainer for this to be addressed.
+
+If adding functionality this again should be accompanied with tests to show that it adds the desired behaviour. Moreover, updates to package documentation, including changes or additions to vignettes might be needed. Expect back and forth with the package maintainer, as they might well have feedback on the implementation you propose.
+
+## Opening pull requests
+
+Changes to packages should come via pull requests. Create a branch or a fork of the code, make your change, and open your pull request. If opening a pull request, more than anything try to create a pull request that will be easy for the package maintainer to review and merge. A pull request will be better for everyone involved when it addresses just one specific issue. One quick way to create complexity for the maintainer is to open a pull request that addresses multiple issues at the same time. Although this could be more efficient for the person opening the pull request, it often slows down the review by increasing the complexity of the review for the maintainer.  
+
+As the bare minimum a 
+
+
+## Reviewing pull requests
+
+
+###  Documenting the package
+Run the below to update and check package documentation:
+``` r
+devtools::document() 
+devtools::run_examples()
+devtools::build_readme()
+devtools::build_vignettes()
+devtools::check_man()
+```
+
+Note that `devtools::check_man()` should not return any warnings. If your commit is limited to only package documentation, running the above should be sufficient (although running `devtools::check()` will always generally be a good idea before submitting a pull request.
+
+### Run tests
+Before starting to contribute any code, first make sure the package tests are all passing. If not raise an issue before going any further (although please first make sure you have all the packages from imports and suggests installed). As you then contribute code, make sure that all the current tests and any you add continue to pass. All package tests can be run together with:
+``` r
+devtools::test()
+```
+
+Code to add new functionality should be accompanied by tests. Code coverage can be checked using: 
+``` r
+# note, you may first have to detach the package
+# detach("package:IncidencePrevalence", unload=TRUE)
+devtools::test_coverage()
+```
+
+### Adhere to code style
+Please adhere to the code style when adding any new code. Do not though restyle any code unrelated to your pull request as this will make code review more difficult.  
+
+``` r
+lintr::lint_package(".",
+                    linters = lintr::linters_with_defaults(
+                      lintr::object_name_linter(styles = "camelCase")
+                    )
+)
+```
+
+### Run check() before opening a pull request
+Before opening any pull request please make sure to run: 
+``` r
+devtools::check() 
+```
+No warnings should be seen. 
+

documenting_functions.qmd

@@ -0,0 +1 @@
+# Documenting functions

function_interfaces.qmd

@@ -0,0 +1 @@
+## Function interfaces

function_outputs.qmd

@@ -0,0 +1 @@
+# Function outputs

index.qmd

@@ -1,3 +1,3 @@
-# Geeting started
+# Getting started
 
 This is an **opinionated** book on how we develop packages in the omopverse.

input_validation.qmd

@@ -0,0 +1 @@
+# Input validation

omop_packages.qmd

@@ -0,0 +1 @@
+# OMOP packages

optimising_code.qmd

@@ -0,0 +1 @@
+

part_five.qmd

@@ -0,0 +1 @@
+# Maintaing a package

part_four.qmd

@@ -0,0 +1 @@
+# Writing code

part_one.qmd

@@ -0,0 +1 @@
+# Principles

part_three.qmd

@@ -0,0 +1 @@
+# Adding unit tests

part_two.qmd

@@ -0,0 +1 @@
+# Contributing documentation

principles.qmd

@@ -1,16 +1,16 @@
 # Principles
 
-- Before developing the package
-  - scope
-  - how it fits within the ecosystem
+-   Before developing the package
+    -   scope
+    -   how it fits within the ecosystem
 -   classes (they are deffined in omopgenerics)
 -   error messages
     -   Why?
     -   How?
 -   naming
     -   functions
-      -  strcutures: `generate...CohortSet`, `...Cohort`, `add...`, `summarise...`, `plot...`, `table...`, 
+    -   strcutures: `generate...CohortSet`, `...Cohort`, `add...`, `summarise...`, `plot...`, `table...`,
     -   arguments
-- input validation
-- testing
-- reexport
+-   input validation
+-   testing
+-   reexport

readme.qmd

@@ -0,0 +1 @@
+# Readme

references.qmd

@@ -0,0 +1,4 @@
+# References {.unnumbered}
+
+::: {#refs}
+:::

releasing.qmd

@@ -0,0 +1 @@
+# CRAN

unit_testing.qmd

@@ -0,0 +1 @@
+# Unit testing

vignettes.qmd

@@ -0,0 +1 @@
+