Contributing

Pierre Ossman (Work account) edited this page Dec 8, 2017 · 9 revisions

We accept code via pull requests. There are several guidelines that we expect contributors submitting code requests to follow. If you have issues following any of these guidelines, feel free to let us know.

Committer Requirements:

  • Respect: Be respectful of project users and contributors (even if they are not being respectful).

  • Attribution/Licenses: do not include code with unclear licenses or that is incompatible with the existing project licenses. Cite any third party code in the commit, in code comments, and the project documentation.

Committer Expectations:

  • Support the community: provide feedback for issue reports and mailinglist questions (https://groups.google.com/forum/#!forum/novnc).

  • Pull requests: Review pull requests and give feedback to help the submitter improve the proposed changes. Merge pull requests once they are of high quality and align with project goals/vision.

  • Collaborate: for non-obvious changes seek review/input from other team members.

  • Support upstream: noVNC and websockify are used by other projects with large user bases (e.g. OpenStack, ThinLinc). Try not to make changes that break upstream projects, or if you must make breaking changes make sure it is well documented and give plenty of warning.

  • Testing: test noVNC and websockify with multiple browsers. Test websockify with python 2.4 - 3.X. Additionally, you are encoraged to write automated unit tests using Mocha -- see Testing

Code Commit (and pull request) Checklist

The general rule is Do the work up front to make code changes understandable/maintainable to anyone who may be reviewing/accepting/fixing the changes.

  • Code style: match the current coding style of the file(s) you are working on. We don't have an official coding style guide, but the general idea is:

    • Use four spaces instead of tabs
    • prefix private variables and functions with an _
  • Modular: keep the code modular. Do not violate API, modularity, and logical layering of the project. See Modules API. For example, DOM manipulation should be limited to app/webutil.js and app/ui.js.

  • Commit size: each commit should represent a single logical change to the code base. A pull request or push can have multiple commits that represent a larger collection of functionality, but each commit should represent just one change if possible. Each commit should also be functional (i.e. pass testing) so that reverting and bisecting is possible.

  • Clean history: Squash your commits down in to a clean commit history. For instance, there should not be "cleanup" commits where you fix issues in previous commits in the same pull request. Before you go to commit, use git rebase -i to squash these changes into the relevant commits. For instance, a good commit history might look like:
    • Added support for FOO encoding
    • Added support for BAR message
    • Placed Button in UI to Trigger BAR
  • Commit Message Header: use a short (less than 70 characters) and descriptive first line for the commit. The first line should also refer to issues fixed.

  • Commit Message Body: a full explanation of the change including:

    • why the change was made
    • any additional information that is not covered by the inline comments that would be needed by an amateur developer to understand the change.
    • how the change was tested
    • cite any third party code including the license and the original location and author
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.