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
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
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 seem 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
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 / …)
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.
I am proposing the following be added to the wiki as a starting point which may be tweaked as experience is gained. Please comment:
Zynthian Developer Guide
Bug fixes and enhancements should be offered as pull requests:
Add bug or feature request to GitHub issue tracker describing the development (if not already existing)
Fork Zynthian repositories
Create branch from “Testing” called bug/XXX_description or feature/XXX_description where XXX is the GitHub ticket number describing the bug or feature request that is being addressed
Develop fix / enhancement and commit to your git fork branch
Merge main Zynthian Testing branch into your fork branch to ensure it is up to date
Test for correct behaviour including as much regression testing as practicable, i.e. try to ensure your change has not broken something else
Submit Pull Request against main Zynthian repositories
Resolve any issues raised during pull request process
Coding Style
Zynthian uses several coding languages including C, C++, Python, BASH, etc. The following is a high-level guide describing a general approach for coding style in all Zynthian modules with specific examples for each language as appropriate. This guide applies to core Zynthian code and should not be applied to upstream code which may have its own coding style.
Every file should include a comment at the top describing:
The function the file performs
A copyright notice including:
The authors of the file content
The date the file was created and last updated
The licence under which the content is published
Attribution for any derived content including:
The author of the original content
The licence under which the original content was published (at the date it was used)
Files should use spaces (not tabs) where practicable. Indentation should be multiples of 4 spaces.
C/C++ should use Kernighan & Ritchie Style (K&R) layout and follow C++ Core Guidelines.
