# 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.
+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 contribute to the project - creating bug reports, opening pull requests,
-as well as commenting on 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.
+There are multiple ways to contribute to the project - creating bug
+reports, opening pull requests, as well as commenting on and engaging in
+discussions about other contributions, to name a few. This document is
+intended 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) or [Discord](https://discord.gg/GZTYR4s).
-We'll be happy to answer as best we can.
+If you have any questions about the contents of this document, the code,
+or how to contribute, please drop us a line on [Gitter][1] or
+[Discord][2]. We'll be happy to answer as best we can.
#### Table of Contents
1. [Things to keep in mind](#things-to-keep-in-mind)
## 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:
+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.
-* It's a good idea to open your PR early, so that you can get quick feedback. Tag it with "WIP" in the title.
-* 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.
+* It's a good idea to open your PR early, so that you can get quick
+feedback. Tag it with "WIP" in the title.
+* 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.
+* 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.
+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.
+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.
```
#### 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`.
+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.
+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/).
+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][3].
```bash
$ git config --global user.signingkey QF3G6A39
```
#### 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,
+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
* Always keep the second line blank.
-* If you need a longer description, keep all subsequent more descriptive lines at 72 characters or less.
+* If you need a longer description, 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.
+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.
+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)
+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
+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
```
#### 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
+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).
+If it executes without any problems, you're good to go and ready to move
+on to creating your [Pull Request][4].
## 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.
+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.
+* 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 short explanation of why you think these changes are neccesary, if it is not readily apparent from
-the rest of the pull request.
+* 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 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 should be adhered to religiously. In general, this is the
-same as following the MSDN and CoreFX guidelines with some changes. A complete style guide is in the works.
-* 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.
+same as following the MSDN and CoreFX guidelines with some changes. A
+complete style guide is in the works.
+* 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.
+* 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.
+* 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.
+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".
+* 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.
+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.
+* 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).
+* 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.
+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.
+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 better.
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.
+* 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.
+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) are 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.
+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
+Every bug report must follow the [Issue Template][5]. 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 OpenTK version that
+exhibits the issue should be included as a package reference, either
+from NuGet or MyGet.
+
+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, Discord, 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 :)
\ No newline at end of file
+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
+:)
+
+[1]: https://gitter.im/opentk/opentk
+[2]: https://discord.gg/GZTYR4s
+[3]: https://help.github.com/articles/signing-commits-with-gpg/
+[4]: #pull-requests
+[5]: https://github.com/opentk/opentk/blob/develop/.github/ISSUE_TEMPLATE.md
\ No newline at end of file
projects / platform / core / csapi / opentk.git / commitdiff