diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..05df3f1c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,328 @@ +# 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 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][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) +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. +* 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. + +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][3]. + +```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 +* Always keep the second line blank. +* 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. + +#### 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][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. + +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 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. +* 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 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. + +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. + +## Bug Reports +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 +:) + +[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