Collaboration guidelines for Github projects

Development
6

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.

Python code should be PEP8 compliant.

All functions should be prefixed with a comment that describes:

  • The purpose of the function
  • Each parameter type and purpose
  • Return type and content
  • Additional notes on use only if necessary

For C/C++ code this comment should be in the header file and comply with JavaDoc format.

Naming convention

  • Names of classes, functions, variables, etc. should be descriptive but not too long (developer’s discretion)
  • Names of classes should be CamelCase
  • Names of functions and variables should be lowercase words separated by underscore
  • Constants and macros should by uppercase words separated by underscore
6 Likes