developer and contributor process overview

Why?

Process is extremely important for coordinating among multiple members. Though osmosis will start small, the goal is to minimize the bus factor by properly organizing, documenting, and testing packages to keep knowledge in the code and allow other users/developers to quickly and confidently contribute.

General Contributor Guidelines

Code on the master branch should always be runnable. The general git workflow for all projects is on the fork-and-branch model. That is, all work should be done on a separate fork, and for each new task, a separate branch should be created. This keeps the process consistent between those with commit access. Details can be found here. The basics are as follows:

1. Fork the repository
2. create a new branch, with an informative name (eg )
3. create a pull request to the original repository

Even for single developer projects, no commits should be performed directly on the master branch.
Code merged through pull requests provides a trail of effort for specific work and the surrounding discussion.

Before a pull-request may be merged into master it must contain:

• unit tests, or a well-justified reason that unit tests are not applicable for the proposed changes.
• documentation through the language-specific guide (eg Roxygen2 in R, godoc in go, doxygen for cpp).
• code written following the code quality and standards outlined below.

Code quality and standards

Every effort should be made to write code in modern and idiomatic styles. If a contributor is unsure about style they should request a code review or post to the discussion forum. This is somewhat subjective, and will be up to the project leads to help mentor and enforce.

For R code this involves:

1. use tidyverse idioms:
   • top level functions should interact with a dataframe, and have a first argument specified by .df
   • functions that interact with a vector should have a leading argument specified as x or .x
2. functions should handle vectorized inputs
3. minimize loops for computationally bounded sections (eg fine to loop over names in a dataframe, not necessarily all rows)
4. All code should follow the style guide outlined in the tidyverse style guideline
   • one exception is an explicit return should be used in all instances
5. Document with Roxygen2 tags
6. Build package documentation with pkgdown

Additional language reference guidelines will be created over time.

Versioning

All projects must follow semantic versioning with the pattern <major>.<minor>.<patch>. The versions correspond to:

• patch versions for bugfixes
• minor versions for new features
• major versions for any breaking changes.

When a breaking change occurs, every effort will be made to also introduce deprecation warnings in the previous minor version so that our users learn about the upcoming changes and migrate their code in advance.

Every pull request should be tagged with a label marking whether the change should go in the next patch, minor, or a major version. Generally the release timelines should be approximately:

• new patch versions every few weeks
• minor versions every few months
• major versions maximum one or two times a year.

Every significant change is documented in a CHANGELOG file.

Continuous Integration

• All projects should use Circle-CI and Appveyor to test and vet all code. Pull requests should not be merged unless all tests pass on all CI platforms.