Contributing - novnc/noVNC GitHub Wiki

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.

Contributor expectations

  • Respect: Be respectful to other 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.

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

Checklist for commits and pull requests

To make your changes as understandable and maintainable as possible, please follow the checklist below.

  • Code style: match the current coding style of the file(s) you are working on. The code must pass our lint checks, see Testing#linter. 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

noVNC maintainer goals

  • 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 maintainers.

  • 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.