Added contribution guidelines.

[platform/core/csapi/opentk.git] / CONTRIBUTING.md

# Contribution guidelines for OpenTK

## Preface
First of all, thank you for considering contributing to the OpenTK project! It's a large codebase
with a lot of twists and turns, and a helping hand is always welcome.

There are multiple ways to contribue to the project - creating bug reports, opening pull requests, 
commenting on either and engaging in discussions about other contributions to name a few. This
document is intented as a set of guidelines to help your contribution get accepted faster, maintain
a high standard, and to help us (the maintainers) set a few ground rules for working with us.

If you have any questions about the contents of this document, the code, or how to contribute, please
drop us a line on [Gitter](https://gitter.im/opentk/opentk). We'll be happy to answer as best we can.

#### Table of Contents
1. [Things to keep in mind](#things-to-keep-in-mind)
2. [Setting Up](#setting-up)
3. [Pull Requests](#pull-requests)
        1. [Bug Fixes](#bug-fixes)
        2. [New Features](#new-features)
        3. [Cosmetic & Stylistic Changes](#cosmetic-&-stylistic-changes)
        4. [Breaking Changes](#breaking-changes)
4. [Bug Reports](#bug-reports)
5. [Discussions & Suggestions](#discussions-&-suggestions)


## Things to keep in mind
Like a lot of other modern projects, OpenTK is written for multiple platforms and operating systems.
Therefore, it's important to keep this in mind when contributing to the project - otherwise, it may 
make accepting your contribution much more difficult. You'll want to consider that the bug you're 
experiencing might not be present on other platforms or system configurations, or that your pull
request doesn't take all platforms into account. Sometimes this important, sometimes it's not.

OpenTK is also (as previously mentioned) a very large codebase which has seen a lot of people and a 
lot of styles over the years. This is reflected in the deeper, darker parts of the codebase where
mixed styles, weird naming, bizarre code and eldritch sorcery abound. What may seem like a small change
on the surface could lead you down on a path of unraveling one thread after another, and what started
off as a simple bug fix could transform into a lot of headscratching.

To make this at least somewhat easier, here's a few concrete general tips which you should stick to:

* Always consider cross-platform gotchas.
* Always work in small, iterative chunks which you can easily describe.
* Avoid cosmetic or visual changes, unless your contribution is strictly focused on that.
* Don't be afraid to ask, especially before diving in. There might be someone else working on the very
same thing already!
* Consider how your contribution might affect other contributions. Sometimes one change will break another
if you're not careful.

In terms of these guidelines, the terminology is as follows:
* Must: If your contribution does not follow this rule, it will not be accepted.
* Should: If your contribution does not follow this rule, it has a lower chance of being accepted.
* May: If your contribution does not follow this rule, it's probably not going to matter that much. 
It'd be a nice touch, though.

With that in mind, check the following sections for more concrete and direct guidelines.

## Setting Up
For first-time contributors, there are a few steps that you'll need to go through in order
to start contributing.

#### 1. Get a copy of the code
First, fork OpenTK to your own profile and clone a local copy.

```bash
$ git clone git@github.com:username/opentk.git
$ cd opentk
$ git remote add upstream https://github.com/opentk/opentk.git
```

#### 2. Create a working branch
Development is done against the `develop` branch - this is where all the magic happens. Your
changes should always be based on this branch, so in order to start working, create a new branch
with an appropriate name and base it on `develop`.

```bash
$ git checkout -b my-branch -t origin/develop
```

#### 3. Let git know who you are
In order to better track changes and who does what, it's a good practice to give git some information
about yourself.

```bash
$ git config --global user.name "John Doe"
$ git config --global user.email "john.doe@example.com"
```

Optionally, you can also add your public GPG key and sign your commits - that way, there is no question
that it's definitely you that's created the commit. GitHub has some excellent information on how to do
this and why it's a good idea - [Signing Commits With GPG](https://help.github.com/articles/signing-commits-with-gpg/).

```bash
$ git config --global user.signingkey QF3G6A39
$ git config --global commit.gpgsign true
```

#### 4. Commit changes
Once you've finished up a change, it's time to commit it. In doing so, you'll be writing some sort of 
commit message, and there are some guidelines for how this should be formatted. Primarily, 

* Keep the first line of the commit message 50 characters or less
* If you need a longer description, keep the second line blank, and keep all subsequent more descriptive
lines at 72 characters or less.

The first line is what will be visible on the commit lists on GitHub, so make sure it's as descriptive as 
you can make it.

#### 5. Synchronizing your changes
Sometimes, pull requests and code changes take time, and other contributions are accepted in the meantime.
When this happens, you'll need to synchronize your changes with what's in the main repository. This should
be done using `rebase`, not `merge`, to keep the commit history from being cluttered with merge commits.

If you've not pushed your changes anywhere yet, it's sufficient to simply run (when on your branch)

```bash
$ git fetch upstream
$ git rebase upstream/develop
```

to fetch the latest code and replay your work on it. However, if you've already pushed it, you might run
into some issues when pushing to your fork after rebasing. To get around this, you'll have to forcibly push 
your changes to overwrite what's in your repository.

```bash
$ git fetch --all
$ git rebase upstream/develop
$ git push --force-with-lease origin my-branch
```

#### 6. Opening a pull request
When you feel that you're all done and you've pushed your changes to git, it's time to open a pull request
and have your changes reviewed. Before doing so, run a final test by executing the build script in the 
base directory of the codebase. 

```bash
$ ./build.sh
```

If it executes without any problems, you're good to go and ready to move on to creating your [Pull Request](#pull-requests).  

## Pull Requests
Pull requests are without a doubt one of the more involved contribution types. Primarily, in order for a
pull request to be accepted, it must maintain a high quality, be well tested, and not have any major 
breaking changes (unless absolutely neccesary). There's going to be a lot of stuff dumped on you in the
next few paragraphs, but keep in mind that most are *guidelines*, not hard rules. Stick to them as best
you can, and when in doubt - just ask.

All pull requests must have or do the following:

* A clear, concise and descriptive title. As a rule of thumb, don't make it longer than twelve words or 
72 characters.
* A clear and detailed description of what the pull request has changed. This includes how the behaviour
of the library will change if the pull request is accepted - a maintainer should be able to read your 
description and fully understand what accepting it would mean without having to dive into the code.
* Be based on the `develop` branch of the main OpenTK repository.

All pull requests should have the following: 
* If applicable, a compilable example which demonstrates the changes. A git repository is preferred, and
your changed branch should be included as a submodule.

A pull requests may have the following:
* A short explanation of why you think these changes are neccesary, if it is not readily apparent from 
the rest of the pull request.

All code changes must follow these rules:

* The [Style Guide](https://www.PLACE.HOLDER/style-guide) should be adhered to religiously. In general, this is 
the same as following the MSDN and CoreFX guidelines with some changes.
* All new methods, fields, properties, events, classes, structures and enumerations must have appropriate
XML documentation comments wherein their behaviour is explained. These comments will be visible to the end
user, and should (in combination with the naming of the element) be sufficient to fully understand what 
the element does.
* XML comments on methods must describe each parameter (if any).
* Changes to existing access modifiers should be avoided if at all possible.

Furthermore, your pull request should: 
* Be tested on all applicable platforms. If you do not have access to a platform (not owning a Windows license, 
not having a Mac on hand, not having Linux installed, etc), ask for help testing your fix in Gitter or in your
pull request.

### Bug Fixes
Bug fixes should resolve a single reported issue, or a collection of issues which fall under a single common 
meta-issue. 

Your bug fix must:

* Fix the issue on all supported platforms, or, if not applicable (such as a platform-specific or 
platform-agnostic bug), make it clear that the other platforms will not have the same issue.
* Refer to the issue number using github's pound syntax - for instance , "This PR resolves issue #1".

### New Features
New features should introduce a single feature, capability, or functionality to the library which was not previously
present. No more than one feature may be introduced in any one pull request. 

Your feature addition must:

* Implement the feature on all supported platforms. If the feature cannot be implemented on one platform for some
reason, this must be clearly explained in the pull request and documented in the source code.

Your feature addition should, if applicable and possible:
* Implement a set of unit tests which test the entirety of the added public API surface. These tests must pass
on the CI service (Travis).

Furthermore, if your new feature replaces or makes an existing feature obsolete, this must be clearly stated.
This may prevent your pull request from being accepted in the current development cycle, or it may fast-track 
it depending on the changes.

### Cosmetic & Stylistic Changes
Cosmetic and stylistic changes are those changes which do not affect executing code - that is, the library 
operates exactly the same way before and after change, but the code might look nicer or follow the style guide 
better.

These types of pull requests are given less priority than others, and may have to wait some time.

A cosmetic pull request must:

* Not break any outstanding pull request, or, if both would modify the same code, be prepared to wait 
until the other contribution is accepted or rejected before being considered.
* Change an affected file in its entirety to match the style guide standard that the contribution is using. 
Mixed styles are not permitted. As an example, if the pull request adds an XML comment to a method, it 
should also comment all other code elements which do not have XML documentation in that file.

Cosmetic contributions are not required to change everything in a file. Single atomic cosmetic changes 
(such as applying a single rule from the style guide) is permitted.

### Breaking Changes
A pull request is considered to have introduced a breaking change if it does or wants to do one of 
the following:

* Removes one or more public method, field, property, event, class, structure or enumeration.
* Renames one or more public method, field, property, event, class, structure or enumeration.
* Alters the public behaviour of an existing method or property without fixing a bug or correcting the
behaviour to an expected result.
* Changes the accessibility of a previously public API to a more restrictive accessibility.
* Changes the method signature of a public method (renaming a parameter does not constitute a breaking 
change, and is a cosmetic change).

These types of pull requests are difficult to handle, and are only accepted as part of an active development
cycle. Their contributions will not make it into regular point releases, but can be merged into the next major 
release.

In general, if your pull request introduces a breaking change, you should follow this rule:

* No public-facing API should be deleted or made inaccessible. Instead, you should introduce an alternate method,
field or property and mark the previous one with an `[Obsolete("Use XXX instead.")]` attribute. Code marked obsolete 
in the previous development cycle is deleted when a new cycle begins.

## Bug Reports
Every bug report must follow the [Issue Template](https://github.com/opentk/opentk/blob/develop/.github/ISSUE_TEMPLATE.md). 
Reports which do not follow this template will be closed.

If you can include a compilable example which demonstrates the issue you're having, the chances
that the bug will be fixed increase substantially. It's a lot faster to work with a problem
if you have something that quickly shows you what's going wrong. As with pull requests, a git repository 
is preferred. The latest OpenTK version from NuGet should be included as a package reference.

One important thing - make sure that the problem is actually an issue with OpenTK before opening a bug.
It may be a driver issue if it's graphical, or a library problem if it's input-related. It may be
a problem with your code, or it might be an issue in a library you use. As with most things, asking for
help on Gitter or other related forums will help you solve your problem faster and prevent invalid bug 
reports from being opened.

## Discussions & Suggestions
We're always open to suggestions and discussions about current and future features and goals of the library. 
Most of these discussions take place on Gitter, but for larger projects and goals it might be a good idea
to create a github project tracker together with the maintainers. If you think the discussion warrants a 
more permanent forum, talk to us :)