CONTRIBUTING.md

You are welcome to file issues or, even better, contribute code to this repo. If you want to report an issue, please read FAQ 1 first.

Issues

For bug reports, please provide a minimal reproducible example. By "minimal", I mean you should reduce your example as much as possible right before the problem you want to report disappears. By doing this, you may be able to figure out what the problem really is before reporting to me. Please do not make me read your hundreds of lines of code (most of which are irrelevant to the bug), or understand dozens of variables in your particular dataset (use a simple built-in dataset in R instead, such as iris or mtcars, or simulated data). Make your example self-contained in one single document, i.e. avoid reading external files if possible, which you may forget to attach to your bug report.

To include a verbatim chunk of arbitrary text, indent it by four spaces, especially when it contains backticks, e.g.

    A sample document.

    ```{r}
    1 + 1  # a line of code
    ```

    Another paragraph.

If it is just a chunk of R code (or other languages) and you want syntax highlighting, you may use three backticks to format it, e.g.

```r
rnorm(10)
```

Pull requests

You may expedite bug fixes and new features by doing the work by yourself. For very simple changes such as fixing typos, you can just edit the file by clicking the button Edit after you open it here on Github. For more complicated changes, you will have to manually create a pull request (PR) after forking this repository. In the latter case, you are recommended to create a new branch instead of always working on the master branch, and please always rebase against my master branch (sometimes you will need to force push, i.e. git push -f, after rebasing):

# suppose your-branch-name is your new branch name
git pull --rebase https://github.com/yihui/knitr.git your-branch-name

If your PR contains commits that revert each other, or attempts that failed, you need to clean the GIT history (and force push). For example, you may combine all the last 5 commits into one:

git reset --soft HEAD~5
# then git add/commit/push

Interactively rebasing a few commits is also very helpful in this case, which gives you granular control over the commits, e.g. git rebase -i HEAD~5.

Testing

To make sure you did not break anything, you need to run tests, which are done through the testit package. If you added any features, add your own tests in tests/testit/.

Travis CI

If you are lazy or do not understand what I said above, just push commits to your repo, submit a PR, wait for a few minutes, then take a look at the Commits panel -- if you see green check marks ✔ on your commits, you are fine. Travis CI will run the tests automatically for me. If your pull request passes the tests, you see green check marks, otherwise you see red crosses, and you will probably get email notifications as well.

• An example PR that passed the check
• An example PR that failed

When your PR does not pass the check, you need to click on the red cross to see details. There are two sets of tests: R CMD check on the package source, as well as the test on examples. The former is basically the unit tests, and the latter is to make sure your changes does not break my existing examples in the knitr-examples.

Roxygen2 documentation

If your changes involve the roxygen2 documentation, please do not include the changes under the man/ directory, which are generated by roxygenize(). I will run roxygenize() by myself after I merge your PR. You should keep the changes in your PR minimal by excluding the roxygen2 artifacts from your GIT commits, so it will be easier for me to review your PR.

Misc

For a non-trivial fix or feature implementation, please let me know before you start working on it, since I do not want to waste too much of your time on something that I may not really want.

Thanks, and happy hacking.