From 36fa91d065a1a5bb33ecb0b33335e8d278731fd9 Mon Sep 17 00:00:00 2001 From: Victor Berger Date: Sat, 13 Oct 2018 13:47:18 +0200 Subject: [PATCH 1/7] Introduce CONTRIBUTING.md --- CONTRIBUTING.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..de324fcec7 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,65 @@ +# Winit Contributing Guidelines + +## Scope + +Winit aims to provide a generic platform abstracting the main graphic platforms (Windows, MacOS, x11, +Wayland, Android, iOS and the web platform via Emscripten). + +Most platform expose capabilities that cannot be meaningfully transposed to the others. Winit does not +aim at supporting every single functionnaly of every platform, but rather abstract the set of +capabilities that is common to all platforms. In this context, APIs exposed in winit can be split into +different "support levels": + +- Tier 1: features which are in the main scope of winit. They are part of the common API of winit, and + are taken care of by the maintainers, and them not working correctly is considered a bug in winit. +- Tier 2: some platform specific features can be sufficiently fundamental to the platform that winit can + integrate support for them in the platform-specific part of the API. These features are not considered + directly handled by the maintainers of winit. If you have a strong incentive to have such a feature + integrated in winit, consider implementing it and proposing yourself to maintain it in the future. +- Tier 3: these features are not directly exposed by winit, but rather can be implemented using the + raw handles to the underlying platform that winit exposes. If your feature of interest is rather + niche, this is probably where it belongs. + +The exact list of supported Tier 1 features is tracked in this issue: +[#252](https://github.com/tomaka/winit/issues/252). + +## Reporting an issue + +When reporting an issue, in order to help the maintainers understand what the problem is, please make +your description of the issue as detailed as possible: + +- if it is a bug, please provide clear explanation of what happens, what should happen, and how to + reproduce the issue, ideally by providing a minimal program exhibiting the problem +- if it is a feature request, please provide a clear argumentation about why you believe this feature + should be supported by winit + +## Making a pull request + +When making a code contribution to winit, before opening your pull request, please make sure that: + +- you tested your modifications on all the platforms impacted, or if not possible detail which platforms + were not tested, and what should be tested, so that a maintainer or an other contributor can test them +- you updated any relevant documentation in winit +- you left comments in your code explaining any part that is not straightforward, so that the + maintainers and future contributors don't have to try to guess what your code is supposed to do + +Once your PR is open, you can ask for review by a maintainer of your platform. Winit's merging policy +is that a PR must be approved by at least two maintainers of winit before being merged, including +at least a maintainer of the platoform (a maintainer making a PR themselves counts as approving it). + +## Maintainers & Testers + +Winit is managed by several people, each with their specialities, and each maintaining a subset of the +backends of winit. As such, depending on your platform of interest, your contacts will be different. + +This table summarizes who can be contacted in which case, with the following legend: + +- `M`: is a main maintainer for this platform +- `T`: has the ability of testing the platform +- ` `: knows nothing of this platform + +| Platform | Windows | MacOS | x11 | Wayland | Android | iOS | Emscripten | +| :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | +| @francesca64 | ? | ? | ? | ? | ? | ? | ? | +| @mitchmindtree | ? | ? | ? | ? | ? | ? | ? | +| @vberger | | | T | M | | | | \ No newline at end of file From 6220bf2465e1de85867db503e79dd6ee8c0f5b02 Mon Sep 17 00:00:00 2001 From: Victor Berger Date: Mon, 15 Oct 2018 09:29:50 +0200 Subject: [PATCH 2/7] typos --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index de324fcec7..56a982d596 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,7 @@ Winit aims to provide a generic platform abstracting the main graphic platforms Wayland, Android, iOS and the web platform via Emscripten). Most platform expose capabilities that cannot be meaningfully transposed to the others. Winit does not -aim at supporting every single functionnaly of every platform, but rather abstract the set of +aim at supporting every single functionaly of every platform, but rather abstract the set of capabilities that is common to all platforms. In this context, APIs exposed in winit can be split into different "support levels": @@ -45,7 +45,7 @@ When making a code contribution to winit, before opening your pull request, plea Once your PR is open, you can ask for review by a maintainer of your platform. Winit's merging policy is that a PR must be approved by at least two maintainers of winit before being merged, including -at least a maintainer of the platoform (a maintainer making a PR themselves counts as approving it). +at least a maintainer of the platform (a maintainer making a PR themselves counts as approving it). ## Maintainers & Testers @@ -62,4 +62,4 @@ This table summarizes who can be contacted in which case, with the following leg | :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | | @francesca64 | ? | ? | ? | ? | ? | ? | ? | | @mitchmindtree | ? | ? | ? | ? | ? | ? | ? | -| @vberger | | | T | M | | | | \ No newline at end of file +| @vberger | | | T | M | | | | From a33dc5f453b606622eb0e2f08339d047753369bc Mon Sep 17 00:00:00 2001 From: Victor Berger Date: Thu, 18 Oct 2018 22:08:33 +0200 Subject: [PATCH 3/7] review --- CONTRIBUTING.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 56a982d596..3eec1a133d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,14 +5,15 @@ Winit aims to provide a generic platform abstracting the main graphic platforms (Windows, MacOS, x11, Wayland, Android, iOS and the web platform via Emscripten). -Most platform expose capabilities that cannot be meaningfully transposed to the others. Winit does not -aim at supporting every single functionaly of every platform, but rather abstract the set of +Most platforms expose capabilities that cannot be meaningfully transposed to the others. Winit does not +aim to support every single functionality of every platform, but rather to abstract the set of capabilities that is common to all platforms. In this context, APIs exposed in winit can be split into different "support levels": - Tier 1: features which are in the main scope of winit. They are part of the common API of winit, and - are taken care of by the maintainers, and them not working correctly is considered a bug in winit. -- Tier 2: some platform specific features can be sufficiently fundamental to the platform that winit can + are taken care of by the maintainers. Any part of these features that is not working correctly is + considered a bug in winit. +- Tier 2: some platform-specific features can be sufficiently fundamental to the platform that winit can integrate support for them in the platform-specific part of the API. These features are not considered directly handled by the maintainers of winit. If you have a strong incentive to have such a feature integrated in winit, consider implementing it and proposing yourself to maintain it in the future. @@ -38,10 +39,11 @@ your description of the issue as detailed as possible: When making a code contribution to winit, before opening your pull request, please make sure that: - you tested your modifications on all the platforms impacted, or if not possible detail which platforms - were not tested, and what should be tested, so that a maintainer or an other contributor can test them + were not tested, and what should be tested, so that a maintainer or another contributor can test them - you updated any relevant documentation in winit - you left comments in your code explaining any part that is not straightforward, so that the maintainers and future contributors don't have to try to guess what your code is supposed to do +- your PR adds an entry to the changelog file Once your PR is open, you can ask for review by a maintainer of your platform. Winit's merging policy is that a PR must be approved by at least two maintainers of winit before being merged, including From 4a33baacdbbc9d8fe92b6830b4db5d18cc83a067 Mon Sep 17 00:00:00 2001 From: Victor Berger Date: Sun, 4 Nov 2018 10:40:45 +0100 Subject: [PATCH 4/7] Update maintainers table --- CONTRIBUTING.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3eec1a133d..b180862510 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -63,5 +63,6 @@ This table summarizes who can be contacted in which case, with the following leg | Platform | Windows | MacOS | x11 | Wayland | Android | iOS | Emscripten | | :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | | @francesca64 | ? | ? | ? | ? | ? | ? | ? | -| @mitchmindtree | ? | ? | ? | ? | ? | ? | ? | +| @mitchmindtree | T | | T | T | | | | +| @Osspial | M | | T | T | T | | T | | @vberger | | | T | M | | | | From 7fd631b9dbfa3d1734b2b98df7bc319c1a5a9647 Mon Sep 17 00:00:00 2001 From: Victor Berger Date: Sun, 4 Nov 2018 10:42:50 +0100 Subject: [PATCH 5/7] add the R level for maintainers table --- CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b180862510..1494717daf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -57,6 +57,7 @@ backends of winit. As such, depending on your platform of interest, your contact This table summarizes who can be contacted in which case, with the following legend: - `M`: is a main maintainer for this platform +- `R`: can review code for this platform - `T`: has the ability of testing the platform - ` `: knows nothing of this platform From 2c4d582cd86f7f7037fd8e6626afd08d95870710 Mon Sep 17 00:00:00 2001 From: Victor Berger Date: Tue, 6 Nov 2018 11:21:45 +0100 Subject: [PATCH 6/7] fill @frencesca64 line in the contributor table --- CONTRIBUTING.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1494717daf..67937df7c1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -63,7 +63,10 @@ This table summarizes who can be contacted in which case, with the following leg | Platform | Windows | MacOS | x11 | Wayland | Android | iOS | Emscripten | | :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | -| @francesca64 | ? | ? | ? | ? | ? | ? | ? | +| @francesca64 | R | (M) | M | | (M) | (M) | | | @mitchmindtree | T | | T | T | | | | | @Osspial | M | | T | T | T | | T | | @vberger | | | T | M | | | | + +Platforms MacOS, Android and iOS are currently being handled by @francesca64, but we are looking for +maintainers for these! From c60d7275c64a3328d1b3b884e171de49b0952e90 Mon Sep 17 00:00:00 2001 From: Victor Berger Date: Wed, 7 Nov 2018 14:51:40 +0100 Subject: [PATCH 7/7] review comments --- CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 67937df7c1..0440c6b497 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ ## Scope -Winit aims to provide a generic platform abstracting the main graphic platforms (Windows, MacOS, x11, +Winit aims to provide a generic platform abstracting the main graphic platforms (Windows, macOS, X11, Wayland, Android, iOS and the web platform via Emscripten). Most platforms expose capabilities that cannot be meaningfully transposed to the others. Winit does not @@ -43,7 +43,7 @@ When making a code contribution to winit, before opening your pull request, plea - you updated any relevant documentation in winit - you left comments in your code explaining any part that is not straightforward, so that the maintainers and future contributors don't have to try to guess what your code is supposed to do -- your PR adds an entry to the changelog file +- your PR adds an entry to the changelog file if the introduced change is relevant to winit users Once your PR is open, you can ask for review by a maintainer of your platform. Winit's merging policy is that a PR must be approved by at least two maintainers of winit before being merged, including @@ -61,12 +61,12 @@ This table summarizes who can be contacted in which case, with the following leg - `T`: has the ability of testing the platform - ` `: knows nothing of this platform -| Platform | Windows | MacOS | x11 | Wayland | Android | iOS | Emscripten | +| Platform | Windows | macOS | X11 | Wayland | Android | iOS | Emscripten | | :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | | @francesca64 | R | (M) | M | | (M) | (M) | | | @mitchmindtree | T | | T | T | | | | | @Osspial | M | | T | T | T | | T | | @vberger | | | T | M | | | | -Platforms MacOS, Android and iOS are currently being handled by @francesca64, but we are looking for +Platforms macOS, Android and iOS are currently being handled by @francesca64, but we are looking for maintainers for these!