Welcome to git2r!Source:
Contributions to the
git2r project are welcome and appreciated. Here follow some guidelines and description of the project to make it easier for you to submit pull requests, report issues, and provide feedback.
By contributing to git2r, you agree to release your contribution under the terms of the GPL v2 license.
Sign your work
To improve tracking of who did what, we’ve borrowed the “sign-off” procedure from the Linux kernel project - A Developer’s Certificate of Origin. Although
git2r is a lot smaller project it is a good discipline to follow it.
The sign-off is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to pass it on as a open-source patch. The rules are pretty simple: if you can certify the below:
Developer's Certificate of Origin 1.1 By making a contribution to this project, I certify that: (a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or (b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or (c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it. (d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.
Then you just add a line to every git commit message:
Signed-off-by: Random J Developer <[email protected]>
Using your real name (sorry, no pseudonyms or anonymous contributions).
This line can be automatically added by Git if you configure your
user.email and run the git commit command with the -s option:
git commit -s.
git2r <- libgit2 + R
Internally the git2r package uses the libgit2 C library to interact with a Git repository. C code can be called from R using the
.Call method. However, in order to map the R data structures to the C data structures used by libgit2 an intermediate layer of C code is between the R methods and libgit2, see figure below.
The package is based on S4 classes/methods. Each S4 class is prefixed with
git_ to have the same name as the corresponding libgit2 data structure. The naming strategy for methods is to use the data structure (branch, note, stash) followed by the action (create, list, remove), e.g.
note_remove, etc. However, the naming is not completely consistent in the package, e.g.
init instead of
The package documentation is written with roxygen2 version 4.1.1. All contributed methods and classes must be documented. Moreover, all exported methods should have examples of their usage. Please file an issue if you spot a method in the documentation without an example, or, better yet, a pull request. The recommended way to generate man files from the roxygen documentation is to run the
roxygen target in the
The tests for the package can be found in the
tests folder. All contributions of code should have corresponding tests.
git2r C code is in files prefixed with
git2r_ in the
src folder. The
libgit2 C code is located in
src/libgit2 with dependencies in
The git2r C functions are named with the prefix
module groups related functionality, e.g.
git2r_repository_init. The source code for each module is in
Argument checking: All R arguments must be checked prior to their usage. There are several help functions in
src/git2r_arg.hto facilitate argument checking. The
repoargument is checked in the
git2r_repository_openfunction and returns
Perform the actual work: The error code (return value) from each call to a libit2 function must be checked. In case of an error, initiate cleanup.
Cleanup: All allocated resources must be freed. In case of an error, call
Rf_errorwith the error message.
It’s very important to have a consistent code style, so before submitting, make sure the code matches surrounding code.
To facilitate development a Makefile exists in the root folder with targets for several common tasks. For an introduction to make, see e.g. the minimal make tutorial by Karl Broman.
roxygen Rebuild R documentation with roxygen2. Checks that the correct version of roxygen2 is installed.
check Build package and then run
R CMD checkto test the package.
check_valgrind Build package and then run
R CMD checkwith valgrind to detect possible problems.
valgrind Run all test code with valgrind.
sync_libgit2 Sync git2r with changes in the libgit2 C-library
Clone or pull libgit2 to parent directory from https://github.com/libgit2/libgit2.git
make sync_libgit2. It first removes files and then copy files from libgit2 directory. Next it runs an R script to build Makevars.in and Makevars.win based on source files. To pass
R CMD check git2rthe printf calls must be changed to use the R printing routine
Rprintf. Therefore it runs a
patchcommand to change some lines in the source code to pass
R CMD check git2r.
Build and check updated package
Makevars The code in src is compiled with a Makevars file (Makevars.in and Makevars.win). They are automatically generated from an R script when running this target.
configure Generate a
configure.acwith autoconf. The configure script is used on non-Windows platforms to generate a system-dependent configuration and detect e.g.
clean Remove temporary and object files.