Skip to content

Contributing

Jump to bottom
Charles Daniels edited this page Dec 31, 2020 · 31 revisions

If you're thinking about contributing to the Fyne project - thanks!

To help ensure consistent code and user-experience, we are building this list of standards we follow and ask all contributors to consider this when working on anything to feed into the project.

Commits

  • Source control is using GitFlow - this means that develop is our default branch and master always follows our most recent release. New features should be branched from, and merged back into, develop.
  • Each commit should have 1 purpose. Fixing whitespace or refactoring should be split from feature additions or bug fixing.
  • Continuous integration is run on our main branches and any pull request must pass our standard checks.

Adding API

  • Adding new (public) API needs to be done with careful thought - once added it must be maintained for a long time.
  • Try to match naming and terminology unless introducing a new concept
  • Every new API will need to have a "// Since: x.y.z" line that is the next version number - if you are unsure which version to use, ask in the pull request or chat room

Code style

  • All new code should have tests.

  • Go code will be formatted in the Go default style - this means tab indents amongst other things. Your code can be updated with goimports -w . before pushing code.

  • Try to keep methods short, with clear naming.

  • Where possible, check corner cases and input errors at the top of a method and exit early.

  • The main body of a function should be the least-indented code, where possible.

  • All Go files should have a standardized ordering of the header (everything apart from types and functions) as follows:

    • package
    • imports
    • CGo
    • consts
    • enums
    • vars

  • File should have a single exported type (with some small exceptions) and the following grouping of contents should be followed:

    • [header - see above]
    • exported type (i.e. Widget)
      • type constructor(s)
      • exported methods
      • unexported type methods
    • additional unexported types (i.e. a WidgetRenderer - in the same order as above)

  • Within each grouping above methods should be in alphabetical order.

  • Package functions (i.e. those functions without a type) should be in a separate file, named pkgname.go, with the following content order:

    • [header - see above]
    • exported functions
    • unexported functions

  • Packages with a main function (normally applications) should have a main.go file that follows this structure:

    • [header - see above]
    • main

  • Struct initialization should either be single line, or with each field on a new line, but not a hybrid of the two.

myType{Foo: f, Bar: r, Baz: z}

myType{
  Foo: f,
  Bar: r,
  Baz: z,
}
  • We prefer inline error assignment and check, unless the error is being used elsewhere, this helps keep the scope of the variable small.
if err := myFunc(); err != nil {
  // Handle error
}

Naming

As well as following the Go code style and our file format organisation mentioned above it is also important for code contributions to match our naming scheme. This makes code easier to read in the future and, for public APIs, helps with discoverability and documentation as well.

The following aspects of naming will be checked during a review process (assuming the basic "golint" has already passed):

  • Naming should be clear and spelled using US English
  • Names should be unambiguous but not too long, full words are normally preferred with a few exceptions (such as 'a' for fyne.App or 'w' for a fyne.Window)
  • Public types should have a constructor function with prefix "New...", this function should take the parameters of elements required for a well functioning object.
  • Although optional items should not appear in constructors, a particularly common usage of some parameters could be presented through additional constructors, using a "With..." suffix, like "NewButtonWithIcon".
  • Enum types (groups of consts using iota) should have a named type and would normally add this type name as a prefix for namespacing
  • Callback functions that can be set by external developers should be prefixed with "On..." and use the past tense, for example "OnTapped" or "OnChanged"

Proposals

If you want to propose and discuss a change to the Fyne project, you should refer to the Contributing: Proposals page.

More information about higher level contributions can be found on our website.

Welcome to the Fyne wiki.

Project documentation

Getting involved

Platform details

Clone this wiki locally