Permalink
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
170 lines (132 sloc) 10.7 KB

How to contribute to the ogon project

First and foremost thank you for your contribution \o/. Without you and the other volunteers these projects wouldn't be possible.

You want to get involved? Get started by reporting a bug, suggesting enhancements or new features, contribute code or if you just want to get in touch with us join the irc channel.

Below you'll find some notes and guidelines for contributing to any component of the ogon project. The project's repositories are hosted in the ogon-project GitHub organization. These guidelines are best practices and choices made during the development and are not written in stone, use them on your sole discretion. Also feel free to suggest changes - simply create a pull request with this modified document.

If anything isn't clear or if you have further questions don't hesitate to ask us (see SUPPORT.md).

Report a BUG

Found a bug? - We would like to help you and smash the bug away. We use a single GitHub based issue tracker for all components/parts of the ogon-project.

Before reporting a bug have a look into the very same issue tracker to see if the bug was already reported and if you can add some additional information.

If it's a new bug - create a new issue. To save time and help us identifying the issue, a bug report should at least contain the following:

  • an useful description of the bug - "It's not working" isn't good enough - you must try harder ;)
  • the steps to reproduce the bug
  • if applicable, the command line or the parameters you have used
  • what did you expect to happen?
  • what actually happened?
  • version(s) used
  • Linux distribution and architecture e.g. amd64, Debian
  • if you built it yourself add some notes which branch you have used, also your build parameters can help
  • extra information helping us to find the bug

Thank you for reporting a bug!

Suggest an enhancement or new features

Another simple way to contribute is to suggest enhancements or new features.

Before you get started and create the issue, check our issue tracker if the feature or enhancement wasn't already suggested. Features are labeled "feature" and enhancements "enhancement". In case you want to work on the feature/enhancement yourself (yay - two thumbs UP!) continue reading and get acquainted with our development process.

Code contributions

For all ogon project repositories we use a pull request based workflow. If you never used git or worked with GitHub before there is a lot of good documentation out there. For example the guides on GitHub.

To create a pull request the following steps are necessary:

  1. fork the repository
  2. clone your repository on your workstation
  3. create a local branch and start working on your modification
  4. push the created branch
  5. create the pull request against the main repository

If this is the first time you contribute to any ogon project repository we need you to sign the contributor license agreement (CLA). Have a look to the CLA signing documentation for the how and why and also for further information.

Once the pull request is created it will be tested, reviewed and merged if it meets all criteria (see commit and pull request guidelines).

Commit and pull request guidelines

During development we've established some guidelines that should be taken into account when creating commits and pull request.

  • use the projects coding conventions
  • commit messages should be in the format as described in commit message syntax
  • for repositories with tests: all tests should pass - some of them are possibly run automated when the pull request is created
  • create clean change sets:
    • commits should be atomic (each commit should work on it's own)
    • each commit should compile
      • focus on one subject (feature/fix/..) and don't change anything else
      • do not mix functional and style changes
      • try not to mix refactorings with functional changes
  • if there are ongoing reviews: try not to change the branch - if you need to do changes create fixup commits and clean up the branch once the reviews finished
  • create tests and documentation for new features and enhancements
  • reference fixed issues in the footer of the commit message (see commit message syntax)
  • if a commit or pull request of a different ogon project repository is required to use or run a commit or pull request, reference it in the footer of the commit message (see commit message syntax)

Issue and pull request lables

In the following, you find a list of issue and pull request lables we use. To see all of the issues from a label just click on the name.

Types and states

Label name (and search link) Description
beginner Easier issues that are good as first issues to work on for people that want to contribute.
bug Confirmed bugs.
duplicate This issue is a duplicate of another issue that was reported before
enhancement Request to enhance, improve or change already present functionality.
feature Feature request.
invalid Invalid issues like configuration errors, wrong usage,..
help-wanted Issues where we would appreciate help from the community.
waiting-for-feedback Waiting for feedback of the reporter or any other participant in the issue.
wontfix The reported issue will not be fixed (now).

Components

Label name (and search link) Description
session-manager session manager
rdp-server RDP frontend related issues
core ogon core
backend:x11 x11 backend (xserver)
backend:qt Qt platform for ogon
backend:weston weston backend
channel:rdpdr RDP rdpdr channel
channel:sound RDP sound channel
channel:clipboard RDP clipboard channel
greeter:qt Qt greeter
apps Applications like ogon-shadow or ogon-message

Pull request labels

Label name (and search link) Description
wip The pull request is work in progress and open for discussion. Changes can be expected.
review-pending There are ongoing reviews.
review-required Review is required.
changes-required The pull request was reviews but changes are required.
cla-needed One or more commits in the pull request haven an author that hasn't signed the CLA.