Collaboration guidelines for Github projects

Cross-post from over at zynthian-ui on Github:

In order to be most effective in helping contributors be efficient with this project, I think we can benefit from writing a few things down. A few examples come to mind:

  • Hardware scope for supporting/testing/maintaining features: Only HifiBerry? Also USB? How many input and output channels? Raspberry pi versions (other ARM boards?), OS versions, …
  • Software architecture: how does zynthian_ui deal with threading, mutexes, logging, and performance concerns, and what has driven existing decisions?
  • Testability: how can we start to use unit tests to help prevent regression as the number of contributors grows?
  • Software life cycle: how do we bring features from an idea, to being tested, to being released, with potentially multiple such features developed concurrently?

By making this concrete, expectations can be managed ahead of time, both for contributors and users.

From what I’ve seen, some of these areas have some good ideas behind them already, but I haven’t seen them written down in one place. On Github, generally a CONTRIBUTING.md file would capture this.

In case some of this information has already been written down somewhere else, then let’s have CONTRIBUTING.md link there instead.


Feel free to add suggestions / topics either here or over at Github, we can add them together later. Oh, and let’s save the tabs vs. spaces discussion for last :wink:

3 Likes

Hi,

  • Regarding hardware: as zynthian is an official kit + open sourced code and hardware design, we should try to keep a wide variety of supported hardware. But “makers” have to be warned that they could experience some troubles.
    Maybe a dedicated wiki section for self made zynthian box ? (list of known supported hardware, how to debug, building tips …)

  • Software life cycle: this is crucial imho. To be more explicit, we saw here on discourse, many users being disappointed because the os image doesn’t work out of the box, even on the official kit. Maybe a kind of minimal but tested and fully working zynthian image + the ability to add new feature through webconf could be a solution.

Now, more in my concern:
I’m totally new in python programming and even more in C or C++.
So, what would really help me a lot for making “the big jump” in code contribution is :

  • more comments in code
  • some general description of major class / functions

Hope that this was a good contribution :rofl:

1 Like

You can never have the correct amount of comment. Some want more whilst some want less. I tend to add quite a few comments so you can take a look at my code for some tips.

I tend to add a comment to each function describing it’s purpose, the parameters and return value. I think this would be beneficial to have as a standard coding approach.

I would love to see automated unit testing. I have written a few test cases here but it is very time consuming and never send to be complete.

And comments need maintaining, Most python code comments infrequently except as a sting at the top of each function or method where one should/must describe the method function or class and what it does.

This is the correct place because it will be extracted as doc by processes higher up but as with all things Python there is one source . . .PEP-8

Which says this about comments …

I can share my experience on unit testing (and documentation/comments), which is mostly from a context of writing systems for long-term maintainability by people that come and go.

Writing computer software is about 3 things:

  • Why are we writing a piece of code (also called “business needs”, e.g. “user wants to connect a mono instrument”)
  • What is that piece of code required to do (also called “features”, e.g. “a single jack capture input can be connected to a stereo LV2 plugin”)
  • How is it realizing that functionality (that’s the actual implementation)

Unfortunately, depending on language and style, the code being written mostly only covers “How”, while a year later when someone else is trying to fix or extend the system, “Why” and “What” are much more important.

One can better document the “What” in several ways:

  • Pick well-written method names, that reflect what they’re trying to do.
  • Use a type system for method arguments. In absence of this, provide semantic documentation on expectations for method arguments and return values.
  • When a piece of algorithmic code isn’t obvious (subjective…), add a comment with what it’s trying to do (or, even better, split it off to a method with that comment as name)
  • Write unit tests with verbose names, describing the responsibilities of the unit under test (class / method / file / …)

One can better document the “Why” as well:

  • Have a commit message guideline (see a good example)
  • Have similar guidelines for PR and Issue descriptions
  • Require that all/most/big/… commits are always tied to a Github issue
  • Write integration tests that capture bigger use cases/user stories

This will help capture the development process in a richer way, so it’s easier for a community to see why certain changes are going on, and (hopefully) jump in and helping productively from the start.

Naturally, guidelines are intentions only and should be allowed to develop. Review processes can help make sure that all developers still believe there is merit to them.

1 Like