ryujinx-backup/Opentk
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Reformat document to conform to typical column width.

Browse source
This commit is contained in:
Jarl Gullberg 2018-01-03 14:20:37 +01:00
parent 4e31a412ae
commit 9529caab94
No known key found for this signature in database
GPG key ID: 750FF6F6BDA72D23
1 changed files with 194 additions and 132 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

326
CONTRIBUTING.md
View file

@ -1,17 +1,20 @@
# Contribution guidelines for OpenTK # Contribution guidelines for OpenTK
## Preface ## Preface
First of all, thank you for considering contributing to the OpenTK project! It's a large codebase First of all, thank you for considering contributing to the OpenTK
with a lot of twists and turns, and a helping hand is always welcome. 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, There are multiple ways to contribute to the project - creating bug
as well as commenting on and engaging in discussions about other contributions, to name a few. This reports, opening pull requests, as well as commenting on and engaging in
document is intented as a set of guidelines to help your contribution get accepted faster, maintain discussions about other contributions, to name a few. This document is
a high standard, and to help us (the maintainers) set a few ground rules for working with us. 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 If you have any questions about the contents of this document, the code,
drop us a line on [Gitter](https://gitter.im/opentk/opentk) or [Discord](https://discord.gg/GZTYR4s). or how to contribute, please drop us a line on [Gitter][1] or
We'll be happy to answer as best we can. [Discord][2]. We'll be happy to answer as best we can.
#### Table of Contents #### Table of Contents
1. [Things to keep in mind](#things-to-keep-in-mind) 1. [Things to keep in mind](#things-to-keep-in-mind)
@ -26,40 +29,50 @@ We'll be happy to answer as best we can.
## 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. Like a lot of other modern projects, OpenTK is written for multiple
Therefore, it's important to keep this in mind when contributing to the project - otherwise, it may platforms and operating systems. Therefore, it's important to keep this
make accepting your contribution much more difficult. You'll want to consider that the bug you're in mind when contributing to the project - otherwise, it may make
experiencing might not be present on other platforms or system configurations, or that your pull accepting your contribution much more difficult. You'll want to consider
request doesn't take all platforms into account. Sometimes this important, sometimes it's not. 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 OpenTK is also (as previously mentioned) a very large codebase which has
lot of styles over the years. This is reflected in the deeper, darker parts of the codebase where seen a lot of people and a lot of styles over the years. This is
mixed styles, weird naming, bizarre code and eldritch sorcery abound. What may seem like a small change reflected in the deeper, darker parts of the codebase where mixed
on the surface could lead you down on a path of unraveling one thread after another, and what started styles, weird naming, bizarre code and eldritch sorcery abound. What may
off as a simple bug fix could transform into a lot of headscratching. 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: 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 consider cross-platform gotchas.
* Always work in small, iterative chunks which you can easily describe. * 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. * It's a good idea to open your PR early, so that you can get quick
* Avoid cosmetic or visual changes, unless your contribution is strictly focused on that. feedback. Tag it with "WIP" in the title.
* Don't be afraid to ask, especially before diving in. There might be someone else working on the very * Avoid cosmetic or visual changes, unless your contribution is strictly
same thing already! focused on that.
* Consider how your contribution might affect other contributions. Sometimes one change will break another * Don't be afraid to ask, especially before diving in. There might be
if you're not careful. 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: In terms of these guidelines, the terminology is as follows:
* Must: If your contribution does not follow this rule, it will not be accepted. * Must: If your contribution does not follow this rule, it will not be
* Should: If your contribution does not follow this rule, it has a lower chance of being accepted. accepted.
* May: If your contribution does not follow this rule, it's probably not going to matter that much. * Should: If your contribution does not follow this rule, it has a lower
It'd be a nice touch, though. 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 ## Setting Up
For first-time contributors, there are a few steps that you'll need to go through in order For first-time contributors, there are a few steps that you'll need to
to start contributing. go through in order to start contributing.
#### 1. Get a copy of the code #### 1. Get a copy of the code
First, fork OpenTK to your own profile and clone a local copy. First, fork OpenTK to your own profile and clone a local copy.
@ -71,26 +84,28 @@ $ git remote add upstream https://github.com/opentk/opentk.git
``` ```
#### 2. Create a working branch #### 2. Create a working branch
Development is done against the `develop` branch - this is where all the magic happens. Your Development is done against the `develop` branch - this is where all the
changes should always be based on this branch, so in order to start working, create a new branch magic happens. Your changes should always be based on this branch, so in
with an appropriate name and base it on `develop`. order to start working, create a new branch with an appropriate name and
base it on `develop`.
```bash ```bash
$ git checkout -b my-branch -t origin/develop $ git checkout -b my-branch -t origin/develop
``` ```
#### 3. Let git know who you are #### 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 In order to better track changes and who does what, it's a good practice
about yourself. to give git some information about yourself.
```bash ```bash
$ git config --global user.name "John Doe" $ git config --global user.name "John Doe"
$ git config --global user.email "john.doe@example.com" $ 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 Optionally, you can also add your public GPG key and sign your commits -
that it's definitely you that's created the commit. GitHub has some excellent information on how to do that way, there is no question that it's definitely you that's created
this and why it's a good idea - [Signing Commits With GPG](https://help.github.com/articles/signing-commits-with-gpg/). 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 ```bash
$ git config --global user.signingkey QF3G6A39 $ git config --global user.signingkey QF3G6A39
@ -98,30 +113,36 @@ $ git config --global commit.gpgsign true
``` ```
#### 4. Commit changes #### 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 Once you've finished up a change, it's time to commit it. In doing so,
commit message, and there are some guidelines for how this should be formatted. Primarily, 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 * Keep the first line of the commit message 50 characters or less
* Always keep the second line blank. * 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 The first line is what will be visible on the commit lists on GitHub, so
you can make it. make sure it's as descriptive as you can make it.
#### 5. Synchronizing your changes #### 5. Synchronizing your changes
Sometimes, pull requests and code changes take time, and other contributions are accepted in the meantime. Sometimes, pull requests and code changes take time, and other
When this happens, you'll need to synchronize your changes with what's in the main repository. This should contributions are accepted in the meantime. When this happens, you'll
be done using `rebase`, not `merge`, to keep the commit history from being cluttered with merge commits. 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 ```bash
$ git fetch upstream $ git fetch upstream
$ git rebase upstream/develop $ 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 to fetch the latest code and replay your work on it. However, if you've
into some issues when pushing to your fork after rebasing. To get around this, you'll have to forcibly push 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. your changes to overwrite what's in your repository.
```bash ```bash
@ -131,136 +152,177 @@ $ git push --force-with-lease origin my-branch
``` ```
#### 6. Opening a pull request #### 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 When you feel that you're all done and you've pushed your changes to
and have your changes reviewed. Before doing so, run a final test by executing the build script in the 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. base directory of the codebase.
```bash ```bash
$ ./build.sh $ ./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
Pull requests are without a doubt one of the more involved contribution types. Primarily, in order for a Pull requests are without a doubt one of the more involved contribution
pull request to be accepted, it must maintain a high quality, be well tested, and not have any major types. Primarily, in order for a pull request to be accepted, it must
breaking changes (unless absolutely neccesary). There's going to be a lot of stuff dumped on you in the maintain a high quality, be well tested, and not have any major breaking
next few paragraphs, but keep in mind that most are *guidelines*, not hard rules. Stick to them as best changes (unless absolutely neccesary). There's going to be a lot of
you can, and when in doubt - just ask. 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: 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 * A clear, concise and descriptive title. As a rule of thumb, don't make
72 characters. 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 * A clear and detailed description of what the pull request has changed.
of the library will change if the pull request is accepted - a maintainer should be able to read your This includes how the behaviour of the library will change if the pull
description and fully understand what accepting it would mean without having to dive into the code. 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. * Be based on the `develop` branch of the main OpenTK repository.
All pull requests should have the following: All pull requests should have the following:
* If applicable, a compilable example which demonstrates the changes. A git repository is preferred, and * If applicable, a compilable example which demonstrates the changes. A
your changed branch should be included as a submodule. git repository is preferred, and your changed branch should be included
* A short explanation of why you think these changes are neccesary, if it is not readily apparent from as a submodule.
the rest of the pull request. * 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: All code changes must follow these rules:
* The style should be adhered to religiously. In general, this is the * 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. same as following the MSDN and CoreFX guidelines with some changes. A
* All new methods, fields, properties, events, classes, structures and enumerations must have appropriate complete style guide is in the works.
XML documentation comments wherein their behaviour is explained. These comments will be visible to the end * All new methods, fields, properties, events, classes, structures and
user, and should (in combination with the naming of the element) be sufficient to fully understand what enumerations must have appropriate XML documentation comments wherein
the element does. 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). * 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: 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, * Be tested on all applicable platforms. If you do not have access to a
not having a Mac on hand, not having Linux installed, etc), ask for help testing your fix in Gitter or in your platform (not owning a Windows license, not having a Mac on hand, not
pull request. having Linux installed, etc), ask for help testing your fix in Gitter or
in your pull request.
### Bug Fixes ### Bug Fixes
Bug fixes should resolve a single reported issue, or a collection of issues which fall under a single common Bug fixes should resolve a single reported issue, or a collection of
meta-issue. issues which fall under a single common meta-issue.
Your bug fix must: Your bug fix must:
* Fix the issue on all supported platforms, or, if not applicable (such as a platform-specific or * Fix the issue on all supported platforms, or, if not applicable (such
platform-agnostic bug), make it clear that the other platforms will not have the same issue. as a platform-specific or platform-agnostic bug), make it clear that the
* Refer to the issue number using github's pound syntax - for instance , "This PR resolves issue #1". 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
New features should introduce a single feature, capability, or functionality to the library which was not previously New features should introduce a single feature, capability, or
present. No more than one feature may be introduced in any one pull request. 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: Your feature addition must:
* Implement the feature on all supported platforms. If the feature cannot be implemented on one platform for some * Implement the feature on all supported platforms. If the feature
reason, this must be clearly explained in the pull request and documented in the source code. 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: 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 * Implement a set of unit tests which test the entirety of the added
on the CI service (Travis). 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. Furthermore, if your new feature replaces or makes an existing feature
This may prevent your pull request from being accepted in the current development cycle, or it may fast-track obsolete, this must be clearly stated. This may prevent your pull
it depending on the changes. request from being accepted in the current development cycle, or it may
fast-track it, depending on the changes.
### Cosmetic & Stylistic Changes ### Cosmetic & Stylistic Changes
Cosmetic and stylistic changes are those changes which do not affect executing code - that is, the library Cosmetic and stylistic changes are those changes which do not affect
operates exactly the same way before and after change, but the code might look nicer or follow the style guide executing code - that is, the library operates exactly the same way
better. before and after change, but the code might look nicer or follow the
style better.
A cosmetic pull request must: A cosmetic pull request must:
* Not break any outstanding pull request, or, if both would modify the same code, be prepared to wait * Not break any outstanding pull request, or, if both would modify the
until the other contribution is accepted or rejected before being considered. same code, be prepared to wait until the other contribution is accepted
* Change an affected file in its entirety to match the style guide standard that the contribution is using. or rejected before being considered.
Mixed styles are not permitted. As an example, if the pull request adds an XML comment to a method, it * Change an affected file in its entirety to match the style guide
should also comment all other code elements which do not have XML documentation in that file. 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 Cosmetic contributions are not required to change everything in a file.
(such as applying a single rule from the style guide) is permitted. Single atomic cosmetic changes (such as applying a single rule from the
style guide) are permitted.
### Breaking Changes ### Breaking Changes
A pull request is considered to have introduced a breaking change if it does or wants to do one of A pull request is considered to have introduced a breaking change if it
the following: does or wants to do one of the following:
* Removes one or more public method, field, property, event, class, structure or enumeration. * Removes one or more public method, field, property, event, class,
* Renames one or more public method, field, property, event, class, structure or enumeration. structure or enumeration.
* Alters the public behaviour of an existing method or property without fixing a bug or correcting the * Renames one or more public method, field, property, event, class,
behaviour to an expected result. structure or enumeration.
* Changes the accessibility of a previously public API to a more restrictive accessibility. * Alters the public behaviour of an existing method or property without
* Changes the method signature of a public method (renaming a parameter does not constitute a breaking fixing a bug or correcting the behaviour to an expected result.
change, and is a cosmetic change). * 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 These types of pull requests are difficult to handle, and are only
cycle. Their contributions will not make it into regular point releases, but can be merged into the next major accepted as part of an active development cycle. Their contributions
release. 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: 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, * No public-facing API should be deleted or made inaccessible. Instead,
field or property and mark the previous one with an `[Obsolete("Use XXX instead.")]` attribute. Code marked obsolete you should introduce an alternate method, field or property and mark the
in the previous development cycle is deleted when a new cycle begins. 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 ## Bug Reports
Every bug report must follow the [Issue Template](https://github.com/opentk/opentk/blob/develop/.github/ISSUE_TEMPLATE.md). Every bug report must follow the [Issue Template][5]. Reports which do
Reports which do not follow this template will be closed. not follow this template will be closed.
If you can include a compilable example which demonstrates the issue you're having, the chances If you can include a compilable example which demonstrates the issue
that the bug will be fixed increase substantially. It's a lot faster to work with a problem you're having, the chances that the bug will be fixed increase
if you have something that quickly shows you what's going wrong. As with pull requests, a git repository substantially. It's a lot faster to work with a problem if you have
is preferred. The latest OpenTK version from NuGet should be included as a package reference. 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. One important thing - make sure that the problem is actually an issue
It may be a driver issue if it's graphical, or a library problem if it's input-related. It may be with OpenTK before opening a bug. It may be a driver issue if it's
a problem with your code, or it might be an issue in a library you use. As with most things, asking for graphical, or a library problem if it's input-related. It may be a
help on Gitter or other related forums will help you solve your problem faster and prevent invalid bug 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. reports from being opened.
## Discussions & Suggestions ## Discussions & Suggestions
We're always open to suggestions and discussions about current and future features and goals of the library. We're always open to suggestions and discussions about current and
Most of these discussions take place on Gitter, but for larger projects and goals it might be a good idea future features and goals of the library. Most of these discussions take
to create a github project tracker together with the maintainers. If you think the discussion warrants a place on Gitter, but for larger projects and goals it might be a good
more permanent forum, talk to us :) 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