Added contribution guidelines.
This commit is contained in:
Jarl Gullberg
parent
21bd3e2cff
commit
8991be20bd
1 changed files with 268 additions and 0 deletions
268
CONTRIBUTING.md
Normal file
268
CONTRIBUTING.md
Normal file
|
|
@ -0,0 +1,268 @@
|
||||||
|
# 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 :)
|
||||||
Loading…
Reference in a new issue