ColPrac

ColPrac: Contributor’s Guide on Collaborative Practices for Community Packages

This document describes some best practices for collaborating on repositories. Following these practices makes it easier for contributors (new and old) to understand what is expected of them. It should be linked to in the README.md.

There are many good practices that this document does not cover. These include other members of the wider community reviewing pull requests (PRs) they are interested in, and maintainers encouraging and supporting people who open issues to make PRs to solve them. This document facilitates these other good practices by clarifying what can seem a mysterious process to those who are unfamiliar with it.

This document is also only intended for community practices, it is not suitable for solo projects with one maintainer.

Community Standards

Interactions with people in the community must always follow the community standards,

including in pull requests, issues, and discussions.

Contributing PRs

Reviewing, Approving and Merging PRs

Releases

Becoming a Collaborator (gaining merge rights)


ColPrac: Further Guidance

This page offers some further guidance on conventions that can be helpful when collaborating on projects. This is an expansion on the Collaborative Practices, with more details and extra guidance. Anything detailed here should be considered less important than the main Collaborative Practices.

Guidance on contributing PRs

Guidance on reviewing, approving and merging PRs

Guidance on Package Releases

Incrementing the package version

Unreleased Changes and -DEV

Following the Collaborative Practices, when there are unreleased changes in the repository for an extended period of time the version number in the Project.toml should be suffixed with -DEV. This makes it clear that there are unreleased changes. Which is useful for many things, including quickly understanding why a bug is still occurring, and working out if a bugfix may need to be backported.

Some more details on the use of -DEV.

Changing dependency compatibility

Dropping support for earlier versions of Julia

Accidental breaking releases

Do not panic, these things sometimes slip through.

It is important to fix it as soon as possible, as otherwise people start using the breaking change, and reverting it later causes more problems (c.f. Murphy’s law).

To fix it:

  1. Make a PR which reverts the PR that made the breaking change.
  2. Bump the Patch version number in the Project.toml. It was a bug that a breaking API change was made, so a Patch release is correct to fix it.
  3. Merge the PR and release the new version.

Once the change is reverted you can take stock and decide what to do. There are generally 2 options:

  1. Make a new PR to reimplement the feature in a non-breaking way.
  2. Make a new PR which reverts the reversion, bump the version number to signify it as breaking, and release the new breaking version.

Example

Consider a package which is currently on v1.14.2. I made a PR to add a new feature and tagged release v1.15.0. The next evening, we get bug reports that the new feature actually broke lots of real uses.

Maybe I changed what I thought was an internal function, but one that was actually part of the public API; maybe I accidentally changed the return type, and that was something people depended on. Whatever it was, I broke it, and this was not caught in code review.

To fix it, I revert the change, and then tag release v1.15.1. Hopefully, I also can add a test to prevent that part of the API being broken by mistake.

Now I look at my change again. If I can add the same functionality in a non-breaking way - for example, make a new internal function for my use - then I would do so and tag v1.15.2 or v1.16.0 depending on what had to change. If I cannot make an equivalent non-breaking change, then I would have to make the breaking change and tag v2.0.0.

Guidance on automatically enforcing guidelines

Many of these guidelines can and should be enforced automatically.


Changes that are not considered breaking

Everything on this list can, in theory, break users’ code. See XKCD#1172. However, we consider changes to these things to be non-breaking from the perspective of package versioning.

(This guidance on non-breaking changes is inspired by https://www.tensorflow.org/guide/versions.)

Appendix:

Marking a Repository as following ColPrac:

As mentioned at the top, community repositories following ColPrac, should link to it in their README.md. One way to do that is with a GitHub badge.

ColPrac: Contributor's Guide on Collaborative Practices for Community Packages

[![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor's%20Guide-blueviolet)](https://github.com/SciML/ColPrac)

In many-cases ColPrac serves in the places of a CONTRIBUTING.md, having all the common guidance that you would otherwise put there. If your package has its own CONTRIBUTING.md then you should also link to ColPrac there, and indicate how the contents of ColPrac relates to the CONTRIBUTING.md. For example by stating:

We follow the ColPrac guide for collaborative practices. New contributor should make sure to read that guide. Below are some additional practices we follow.