From 9529caab94a14f64b77f9c2d8ea006cc6fa665be Mon Sep 17 00:00:00 2001 From: Jarl Gullberg Date: Wed, 3 Jan 2018 14:20:37 +0100 Subject: [PATCH] Reformat document to conform to typical column width. --- CONTRIBUTING.md | 326 ++++++++++++++++++++++++++++-------------------- 1 file changed, 194 insertions(+), 132 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 151dc7ad..05df3f1c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,17 +1,20 @@ # 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) @@ -26,40 +29,50 @@ We'll be happy to answer as best we can. ## 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. +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. +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: +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. @@ -71,26 +84,28 @@ $ 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`. +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 @@ -98,30 +113,36 @@ $ 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, +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 @@ -131,136 +152,177 @@ $ 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 +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: +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). +* 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. +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: +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. +* 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. +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 latest OpenTK version from NuGet should be included as a package reference. +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 or other related forums will help you solve your problem faster and prevent invalid bug +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