A Guide to Collaboration

SlickGrid is an open source project that lives on collaboration.

A bit about me, Ben McIntyre (GitHub @6pac).
I'm 50 years old, live in Alice Springs, Australia, I have two kids (8 and 12) and I'm heavily involved in the local Theatre Society. I run a software development business with clients locally and interstate, mainly using .NET. While Alice is a great place to live, it's a small town a long way from anywhere, and it's a struggle being a developer here. And I'm really busy juggling all these things.

SlickGrid is a key part of a framework that I've been developing for several years now. I searched on and off for a year or so, becoming more and more worried that I'd have to build something like it myself, before it came to my attention, and it's a perfect fit. However, now SlickGrid issues are taking up enough time that they are preventing me from progressing the work I started to use SlickGrid for.

What I'm getting at here, is that I'm looking for other people - particularly younger people with more free time - to become involved with this project.
Up till now, I've only given one user, @GhisCoding, 'collaborator' status (meaning he can commit to the repo), and that's because he consistently demonstrated good judgement and delivered high quality code in various pull requests. I could see that he works similarly to how I do, and I trust him to make the right decisions.

That's quite a high bar to clear. I'd like to spell out some principles that I see as key to good collaborative development. If you want commit rights, keep to these principles, consistently offer good quality pull requests, and you'll be well on the way.

These principles apply to ALL open source projects, and even to source control systems generally, so it's well worth your time honing these skills, however experienced you are as a developer. They're actually quite simple - the trick is in being able to recognise incremental conceptually grouped chunks of code.

1. All commits should be for a single issue - the smaller the better

Commits are like transactions in a database - they should leave the code in a stable and consistent state and deliver groups of interdependent changes. Within those limits, they should be as small as possible. A lot of bug fix commits are single liners - the commit message is often longer than the code change. Single feature commits help feature rollback if there is a problem, and allow a specific wanted change to be plucked from a set of other unwanted changes.

2. Pull requests must be for a single specific feature or bug fix

Pull requests (PRs) operate similarly to commits but on a bigger scale. A PR is a logical work unit. It is a common mistake to roll a whole bunch of things into a PR - I have had submissions of PRs with thousands of lines of code changes involving many features. These are never going to be accepted, because (1) it's really hard to test the code for each feature individually, since they are not separated, (2) it's all or nothing and the risk of destabilising the code base is great.
Another common mistake is reformatting unrelated lines of code while adding a feature - sometimes your editor will decide to do this for you, and you may not even be aware of it - but it will show in 'changed files' in the PR. It's OK to reformat parts of the code, but it should be a separate PR. Like commits, PRs should focus on one specific issue, and deal only with that. Small, incremental steps preserve a stable code base.

3. Use architecture to your advantage

SlickGrid has plugins and controls. This architecture allows features to be introduced in a separate package that doesn't change the core code. If you are introducing a major new function as a plugin, much less oversight and checking is necessary before approving PRs. After all, if you break something, it's only going to be in that plugin, not the whole grid.

3. Think general - don't assume that everyone wants it to work the same way you do

It's really easy to get tunnel vision when adding a new feature, and propose a change to core code that supports only exactly what you need. It's really good to take a step back at that point, and ask 'is there an enhancement to core code that will provide generally useful additional functionality for a wide range of use cases, of which mine might only be one?'
Small changes to the core code will generally get through as long as they tick this box - if changes are very specific to a use case, then the grid API quickly becomes overwhelmed with complex and sometimes conflicting options.
When implementing a well considered change, also keep in mind that other use cases may see this functionality unnecessary or even undesirable. The feature should be able to be deactivated. Ideally, offer a concise set of options that is clear and wraps the underlying functionality into easily understood choices.

4. Make non-breaking changes

This is probably the most well understood of the rules, because of SemVer. If a new option is added, it should default to the option that makes the project behave as it did before the change (so it is non breaking).
The decision to release a breaking version (eg. 2.3.x to 3.0.0) is one that is not taken lightly, and usually there is a backlog of desirable breaking changes that are released in one update.

OK - that's about it. Enjoy - and contribute!