:tada: First off, thanks for contributing!:tada:
We welcome all types of contributions, including bug fixes, feature enhancements, bug reports, documentation, graphics, and many others. You might consider contributing by:
codyn is an open source project, and we welcome full participation in the project. Contributions are reviewed and suggestions are made to increase the value of codyn to the community. We strive to incorporate code, documentation, and other useful contributions quickly and efficiently while maintaining a high-quality product.
We use the pull-request model for contributions. See GitHub's help on pull-requests.
In short:
develop
branch and commit your changesDevelopment is managed through the git repository at https://github.com/NCEAS/codyn. The repository is organized into several branches, each with a specific purpose. In GitHub, users will normally see the master
branch, which therefore should reflect the current stable release of the package (rather than confusing people with in-progress proposed changes that are not yet released). Consequently, we will use a GitFlow-inspired release model in which the master
branch always reflects the current stable release, a develop
branch is used for merging finished proposals being prepared for the next release, and feature
branches are used for creating changes to implement specific enhancements and bugfixes. For minor changes that don't require review, such as spelling corrections, grammatical rewording, etc., maintainers can commit changes directly to the develop
branch, and other contributors can do a pull request directly against the develop
branch. The use of feature branches is really focused on managing proposals that need discussion, review, and a decision by the team. Maintainers will make judgement calls on whether an feature branch is needed, and might convert contributed pull requests to a feature branch if they determine that one is needed.
master. The master
branch represents the stable branch that contains the current release. Anybody installing the package will, therefore, by default get the stable release.
develop. Development takes place on the develop
branch, which represents the
changes being planned for the next release. This is where the next release is fully tested,
and all feature changes should be merged onto develop
and tested.
When a set of features are mature and tested and ready for release, they are merged onto the develop
branch to await the next release. The tip of the develop branch always represents the set of features that have been staged for the next release. The version number in all configuration files and the README on the master branch follows semantic versioning and should always be set to either:
master
. For example, 2.8.5
.develop
, the planned next release number with a beta
designator or release candidate rc
designator appended as appropriate. For example, 2.8.6-beta1
or 2.9.0-rc1
.feature. Feature branches should be named as feature_##_short_title
where ##
is the issue number from github that the feature is implementing.
For example,
feature_13_r4
might be a new feature being developed independently but intended to be merged into the develop
branch.
All feature branches should be frequently merged with changes from develop
to
ensure that the development branch stays up to date with other features that have
been tested and are awaiting release. Thus, the develop
branch represents an opportunity
for integration testing of the set of features intended to work together for a
particular release.
The release process starts with integration testing in the develop
branch. Once all
changes that are desired in a release are merged into the develop
branch, we run
the full set of tests on a clean checkout, and conduct any code reviews needed. A pull request
can be used for that review, or it can be done directly for simpler sets of changes.
Once review is completed, make sure all version numbers are set correctly and
documentation is complete on develop
, and then merge to master
, and tag that merge
commit as the release. We use tag names of the form v1.2.3
that reflect the version
of the release. If we are submitting to CRAN, we generally do not tag the release
until it has been accepted by CRAN.
Unit and integration tests. We maintain a full suite of unit tests and
integration tests in the tests
subdirectory.
Any new code developed should include a robust set of unit tests for each public
method, as well as integration tests from new feature sets. Tests should fully
exercise the feature to ensure that it responds correctly to both good data inputs
as well as various classes of corrupt or bad data. All tests should pass before
the develop
branch is merged to master, and all tests should pass before the master
branch is tagged as a release.
Continuous integration. We can use Travis for some of our repositories.
Code should be written to professional standards to enable clean, well-documented, readable, and maintainable software. While there has been significant variablility in the coding styles applied historically, new contributions should strive for clean code formatting. Some of the guidelines we follow include:
Java. For Java code, follow the Google Java Style Guide, with the single exception that indentation is performed with 4 spaces rather than 2. When working on a class that does not follow the conventions, strive to reformat that code module in a single isolated code commit before starting other code changes.
Javadoc. All Java code should be fully documented with JavaDoc comments. Special attention should be paid to documentation of the public API for classes. Documentation should explain both what the code does, but also why it does it in a particular way when appropriate. Class and method documentation should be written to provide sufficient context for people that are not intimately familiar with the rest of the code. Class-level documentation often is strengthened through explaining the role of the class in the architecture. Avoid using tautological definitions that reuse the name of a class or method in its definition. And please be complete.
R. Code for R should follow generally accepted R coding conventions.
In order to clarify the intellectual property license granted with Contributions from any person or entity, you agree to a Contributor License Agreement ("CLA") with the Regents of the University of California (hereafter, the "Regents").
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.