From c859146c4314884407224d893ef3cfc76abca1a1 Mon Sep 17 00:00:00 2001 From: Daniel Stahl Date: Wed, 22 Mar 2017 11:07:16 +0100 Subject: [PATCH 1/4] Added instructions on contributing and requesting changes As per issue #131. --- README.md | 2 ++ introduction/how-to-contribute.md | 17 +++++++++++++++++ introduction/how-to-propose-changes.md | 21 +++++++++++++++++++++ 3 files changed, 40 insertions(+) create mode 100644 introduction/how-to-contribute.md create mode 100644 introduction/how-to-propose-changes.md diff --git a/README.md b/README.md index 823aa126..3aa299a1 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,8 @@ __IMPORTANT NOTICE:__ The contents of this repository currectly reflect a __DRAF ## Contents 1. [Introduction](./introduction/introduction.md) + 1. [How to Propose Changes](./introduction/how-to-propose-changes.md) + 1. [How to Contribute](./introduction/how-to-contribute.md) 1. Eiffel Syntax and Usage 1. [Event Design Guidelines](./eiffel-syntax-and-usage/event-design-guidelines.md) 1. [Event Structure](./eiffel-syntax-and-usage/event-structure.md) diff --git a/introduction/how-to-contribute.md b/introduction/how-to-contribute.md new file mode 100644 index 00000000..6edef507 --- /dev/null +++ b/introduction/how-to-contribute.md @@ -0,0 +1,17 @@ +# How to Contribute + +Contributions can be made by anyone using the standard [GitHub Fork and Pull model](https://help.github.com/articles/about-pull-requests). When making a pull request, keep a few things in mind. +1. Always explicitly connect a pull request to an Issue. See [How to Propose Changes](./introduction/how-to-propose-changes.md) for further information. +1. Make sure you target the correct branch. If you are unsure which branch is appropriate, ask in the Issue thread. +1. Pull Requests will be publicly reviewed, criticized, and potentially rejected. Don't take it personally. + +## Reviewing and Merging Pull Requests +We use the Squash and Merge model, which means that all commits in a Pull Request get squashed into a single commit in the target branch. In other words, the revision history will look like a string of single commits corresponding one-to-one with Issues. + +Pull requests can be merged by members of the [Eiffel team](https://github.com/orgs/Ericsson/teams/eiffel). There is a certain protocol to adhere to, however, as well as expectations on membership. +1. All members of the Eiffel team are expected to make the effort to participate in the review of Pull Requests. Every member may not review everything in detail, but everyone can make the effort to chime in on some. Remember that an expedient high quality reviews are crucial to the long term survival of any open source project. +1. Eiffel team members are strongly encouraged to participate in reviews even if they do not feel entirely qualified to assess the pull request. Looking at changes and participating in review discussions is one of the best ways to learn, and presents an excellent opportunity to ask questions. And remember, participating in a review is not the same as having to make the final decision. +1. Anyone can participate in reviews, not only Eiffel team members. +1. A Pull Request should be approved by at least two Eiffel team members (including the one doing the merging). For this to function well, the above point on participation is critical. +1. Do not feel any pressure to merge Pull Requests. Unless you feel confident about what you are doing, don't press that big green button. Instead, ask a more senior member to make the decision. +1. When squashing and merging, ensure that the description reflects the change. Detailing every individual commit in the Pull Request is unnecessary, as they are squashed anyway. Instead, describe the change as a single thing. That description should always include an Issue reference. A lot of the time a descriptive title and an Issue reference is all that is needed. \ No newline at end of file diff --git a/introduction/how-to-propose-changes.md b/introduction/how-to-propose-changes.md new file mode 100644 index 00000000..58d7756d --- /dev/null +++ b/introduction/how-to-propose-changes.md @@ -0,0 +1,21 @@ +# How to Propose Changes + +Anyone is welcome to propose changes to the Eiffel protocol by creating a new [Issue](https://github.com/Ericsson/eiffel/issues) ticket in GitHub. These requests may concern anything contained in the repo: changes to documentation, changes to definitions, requests for additional information, additional event types, requests for additional examples et cetera. + +When posting a new issue, try to be as precise as possible and phrase your arguments for your request carefully. Keep in mind that defining a shared protocol is often an exercise in finding workable compromises between multiple and often conflicting needs. In particular, pay attention to the following: +1. What type of change is requested? +1. Why would you like to see this change? +1. Can you provide any concrete examples? +1. Which arguments in favor can you think of? +1. Which arguments against can you think of, and why are they outweighed by the arguments in favor? + +Also, keep in mind that just as anyone is welcome to propose a change, anyone is welcome to disagree with and criticize that proposal. + +## Closing Issues +An Issue can be closed by any member of the [Eiffel team](https://github.com/orgs/Ericsson/teams/eiffel). This can happen in various ways, for varying reasons: +1. Issues without conclusion and no activity for at least 14 days may be closed, as a mere housekeeping activity. For instance, an Issue met with requests for further clarification, but left unanswered by the original author, may simply be removed. +1. Issues may simply be rejected if found unfeasible or undesirable. In such cases they shall also be responded to, providing a polite and concise explanation as to why the proposal is rejected. +1. Issues may be closed because they are implemented. Following the successful submission of a pull request addressing an Issue, it will be closed. + +## Proposing Solutions +While we welcome requests for changes (in the form of Issues), we absolutely love ready solutions (in the form of Pull Requests). The best requests are the ones with a Pull Request to go along with it. For more information on how to contribute a Pull Request, please see [How to Contribute](./how-to-contribute.md). From 05b66b8ca775ec04dddbb407e1a1b284ab9c9651 Mon Sep 17 00:00:00 2001 From: Daniel Stahl Date: Wed, 22 Mar 2017 11:14:47 +0100 Subject: [PATCH 2/4] Minor fixes. --- introduction/how-to-contribute.md | 4 ++-- introduction/how-to-propose-changes.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/introduction/how-to-contribute.md b/introduction/how-to-contribute.md index 6edef507..eba8c693 100644 --- a/introduction/how-to-contribute.md +++ b/introduction/how-to-contribute.md @@ -1,7 +1,7 @@ # How to Contribute Contributions can be made by anyone using the standard [GitHub Fork and Pull model](https://help.github.com/articles/about-pull-requests). When making a pull request, keep a few things in mind. -1. Always explicitly connect a pull request to an Issue. See [How to Propose Changes](./introduction/how-to-propose-changes.md) for further information. +1. Always explicitly connect a pull request to an Issue. See [How to Propose Changes](./how-to-propose-changes.md) for further information. 1. Make sure you target the correct branch. If you are unsure which branch is appropriate, ask in the Issue thread. 1. Pull Requests will be publicly reviewed, criticized, and potentially rejected. Don't take it personally. @@ -9,7 +9,7 @@ Contributions can be made by anyone using the standard [GitHub Fork and Pull mod We use the Squash and Merge model, which means that all commits in a Pull Request get squashed into a single commit in the target branch. In other words, the revision history will look like a string of single commits corresponding one-to-one with Issues. Pull requests can be merged by members of the [Eiffel team](https://github.com/orgs/Ericsson/teams/eiffel). There is a certain protocol to adhere to, however, as well as expectations on membership. -1. All members of the Eiffel team are expected to make the effort to participate in the review of Pull Requests. Every member may not review everything in detail, but everyone can make the effort to chime in on some. Remember that an expedient high quality reviews are crucial to the long term survival of any open source project. +1. All members of the Eiffel team are expected to make the effort to participate in the review of Pull Requests. Every member may not review everything in detail, but everyone can make the effort to chime in on some. Remember that expedient high quality reviews are crucial to the long term survival of any open source project. 1. Eiffel team members are strongly encouraged to participate in reviews even if they do not feel entirely qualified to assess the pull request. Looking at changes and participating in review discussions is one of the best ways to learn, and presents an excellent opportunity to ask questions. And remember, participating in a review is not the same as having to make the final decision. 1. Anyone can participate in reviews, not only Eiffel team members. 1. A Pull Request should be approved by at least two Eiffel team members (including the one doing the merging). For this to function well, the above point on participation is critical. diff --git a/introduction/how-to-propose-changes.md b/introduction/how-to-propose-changes.md index 58d7756d..e0cd4879 100644 --- a/introduction/how-to-propose-changes.md +++ b/introduction/how-to-propose-changes.md @@ -15,7 +15,7 @@ Also, keep in mind that just as anyone is welcome to propose a change, anyone is An Issue can be closed by any member of the [Eiffel team](https://github.com/orgs/Ericsson/teams/eiffel). This can happen in various ways, for varying reasons: 1. Issues without conclusion and no activity for at least 14 days may be closed, as a mere housekeeping activity. For instance, an Issue met with requests for further clarification, but left unanswered by the original author, may simply be removed. 1. Issues may simply be rejected if found unfeasible or undesirable. In such cases they shall also be responded to, providing a polite and concise explanation as to why the proposal is rejected. -1. Issues may be closed because they are implemented. Following the successful submission of a pull request addressing an Issue, it will be closed. +1. Issues may be closed because they are implemented. Following the successful merging of a pull request addressing an Issue, it will be closed. ## Proposing Solutions While we welcome requests for changes (in the form of Issues), we absolutely love ready solutions (in the form of Pull Requests). The best requests are the ones with a Pull Request to go along with it. For more information on how to contribute a Pull Request, please see [How to Contribute](./how-to-contribute.md). From 204e0f94154e1271fec477c64a1833a79b5635eb Mon Sep 17 00:00:00 2001 From: Daniel Stahl Date: Wed, 22 Mar 2017 14:49:21 +0100 Subject: [PATCH 3/4] Rephrased instructions on commit messages To emphasize the need of providing context, rather than just listing changes. --- introduction/how-to-contribute.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/introduction/how-to-contribute.md b/introduction/how-to-contribute.md index eba8c693..8ce41b1b 100644 --- a/introduction/how-to-contribute.md +++ b/introduction/how-to-contribute.md @@ -14,4 +14,4 @@ Pull requests can be merged by members of the [Eiffel team](https://github.com/o 1. Anyone can participate in reviews, not only Eiffel team members. 1. A Pull Request should be approved by at least two Eiffel team members (including the one doing the merging). For this to function well, the above point on participation is critical. 1. Do not feel any pressure to merge Pull Requests. Unless you feel confident about what you are doing, don't press that big green button. Instead, ask a more senior member to make the decision. -1. When squashing and merging, ensure that the description reflects the change. Detailing every individual commit in the Pull Request is unnecessary, as they are squashed anyway. Instead, describe the change as a single thing. That description should always include an Issue reference. A lot of the time a descriptive title and an Issue reference is all that is needed. \ No newline at end of file +1. When squashing and merging, ensure that the description reflects the change. Detailing every individual commit in the Pull Request is unnecessary, as they are squashed anyway. Instead, describe the change as a single thing. That description should always include an Issue reference, and should focus on WHY a the change was made, to provide the reader with context. See [this excellent guide](https://chris.beams.io/posts/git-commit) on writing good commit messages. \ No newline at end of file From b2ddf7b2d2bf0c36e4cb7d2cc96a6cbe0365b26c Mon Sep 17 00:00:00 2001 From: Daniel Stahl Date: Wed, 22 Mar 2017 15:54:25 +0100 Subject: [PATCH 4/4] Fixed typo. --- introduction/how-to-contribute.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/introduction/how-to-contribute.md b/introduction/how-to-contribute.md index 8ce41b1b..3f916457 100644 --- a/introduction/how-to-contribute.md +++ b/introduction/how-to-contribute.md @@ -14,4 +14,4 @@ Pull requests can be merged by members of the [Eiffel team](https://github.com/o 1. Anyone can participate in reviews, not only Eiffel team members. 1. A Pull Request should be approved by at least two Eiffel team members (including the one doing the merging). For this to function well, the above point on participation is critical. 1. Do not feel any pressure to merge Pull Requests. Unless you feel confident about what you are doing, don't press that big green button. Instead, ask a more senior member to make the decision. -1. When squashing and merging, ensure that the description reflects the change. Detailing every individual commit in the Pull Request is unnecessary, as they are squashed anyway. Instead, describe the change as a single thing. That description should always include an Issue reference, and should focus on WHY a the change was made, to provide the reader with context. See [this excellent guide](https://chris.beams.io/posts/git-commit) on writing good commit messages. \ No newline at end of file +1. When squashing and merging, ensure that the description reflects the change. Detailing every individual commit in the Pull Request is unnecessary, as they are squashed anyway. Instead, describe the change as a single thing. That description should always include an Issue reference, and should focus on WHY the change was made, to provide the reader with context. See [this excellent guide](https://chris.beams.io/posts/git-commit) on writing good commit messages. \ No newline at end of file