IEEE.org     |     IEEE Xplore Digital Library     |     IEEE Standards     |     IEEE Spectrum     |     More Sites

IEEE SA OPEN is sponsoring All Things Open 2021 and our community will be presenting. Check out our speakers and learn more about the free virtual event!!

Commit 49d7dd98 authored by Alfredo Herrera's avatar Alfredo Herrera
Browse files

Update CONTRIBUTING.md

parent ada0e504
......@@ -4,14 +4,16 @@ Contributing to IEEE SA OSCom open-source peer-review ad-hoc sub-committee proje
===
###### Attribution
this file is based on [Nektar++'s CONTRIBUTING.md](https://gitlab.nektar.info/nektar/nektar/-/blob/master/CONTRIBUTING.md) file under an MIT License.
this file is based on [Nektar++'s CONTRIBUTING.md](https://gitlab.nektar.info/nektar/nektar/-/blob/master/CONTRIBUTING.md) file under an MIT License, and the [SciPy Project Governance](http://scipy.github.io/devdocs/dev/governance/governance.html).
## The project
The IEEE "Open Source peer-review" project is an open document project to draft a recommendation for teh IEEE SA Open Source Committee on how to offer a new service for design alike what IEEE offers for publications. This optional on-demand service is intended for official IEEE open source projects and open source projects included in IEEE Standards. The principles stated in this draft may apply to other projects within and outside of IEEE and for that reason we have decided to open participation on this project to anyone interested and knowledgeable on the topic.
## Contents
This guide should provide you sufficient information to help if you're interested in contributing to IEEE-SA OSCom Open-Source Peer-Review ad-hoc committee, either in reporting bugs or, hopefully, providign ideas to fix them. The peer-review "admin" project repository will not produce any software or hardware design; instead, it will ead to the creation of recommendations for consideration by the IEEE SA Open Source Committee on the topic of peer-review of open source designs.
Contributing is described from the following three points of view:
This guide should provide you sufficient information to help if you're interested in contributing to IEEE-SA OSCom Open-Source Peer-Review ad-hoc committee, either in reporting bugs or, hopefully, providign ideas to fix them. The peer-review "admin" project repository will not produce any software or hardware design; instead, it will produce a document with recommendations for the IEEE SA Open Source Committee on how to implement peer-review of open source designs for official IEEE open source projects and open source projects included in IEEE Standards.
Contributing includes the following:
- [Issues and bug reports](#issues-and-bug-reports)
- [How to contribute](#how-to-contribute)
- [Formatting guidelines](#formatting-guidelines)
- [Contributing to document](#contributing-to-document)
- [Decision Making and Governance](#decision-making-and-governance)
## Issues and bug reports
......@@ -19,11 +21,11 @@ If you believe that you have found a _bug or error_, we would like to know about
- To report a bug or error, please raise an issue on the
**[issue tracker](https://opensource.ieee.org/community/peer-review/admin/-/issues)** -- be
sure to do a quick search and see if anyone has reported the same thing before to avoid duplication.
- Alternatively, you can discuss it on **[ the group chat](https://opensource-connect.ieee.org/opnsrcpeerrview)**
- Alternatively, you can discuss it on **[ the group chat](https://opensource-connect.ieee.org/opnsrcpeerrview)** (you need to be part of project to have access)
It will be *really helpful* if you can include the context in which the bug or error can become obvious. At the minimum, please provide a good description of the problem you're having or that you forsee hapenning.
## How to contribute
## Contributing to document
If you would like to contribute improvements or add new topic/feature, please consider contributing it to the project following this simple process:
1. Fork the [peer-review/admin](https://opensource.ieee.org/community/peer-review/admin/-/forks/new) repository in [`opensource.ieee.org/community`](https://opensource.ieee.org/community/) project space into your own space.
......@@ -36,22 +38,29 @@ If you would like to contribute improvements or add new topic/feature, please co
4. When you are ready to merge your contribution, put a comment in the Merge Request saying that it's ready to be merged.
5. When applicable, please respond to any comments or questions during the merge request processing.
## Formatting guidelines
We have adopted the [GitLab flavoured MarkDown](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md) format, a language that has limited formating and document layout options. To hopefully alleviate this problem, there are a number of fairly simple formatting guidelines you should follow. We are reasonably relaxed about code formatting, but if you can follow the guidelines below this would be fantastic.
### Basic rules
### Formatting guidelines
We have adopted the [GitLab flavoured MarkDown](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md) format, a language that has limited formating and document layout options. To hopefully alleviate this problem, there are a number of fairly simple formatting guidelines you should follow. We are reasonably relaxed about code formatting, but if you can follow the guidelines below this would be fantastic. Basic rules:
- Be concise.
- Limit the numer of references to external resources (external to the repostory).
- Be thorough.
- Use simple gramatical constructs.
## Decision making and Governance
Governance is the framework adopted by the project members to reflect how we will interact with each other and how we will make decisions. When deciding on the model of governance to adopt, we looked at the six elements suggested by [Kimberly McClintock as available from Infoworld](https://www.networkworld.com/article/2204163/the-six-elements-of-open-source-governance.html):
Governance is the framework adopted by the project members to reflect how we will interact with each other and how we will make decisions. We decided to adopt the **Benevolent Dictator For Life** (Hierarchical) model: @alfredoh1234 will has final say on all major project decisions, but counts on the feedback from the group to inform his decisions. Only @alfredoh1234 commits contributions, but merge request are reviewed by the group. @alfredoh1234 may assign issues to community members, but members are welcome to self-assign issues or to open new issues to work on.
Once we start drafting the document to be submitted to IEEE SA OSCom, @alfredoh1234 will appoint community members to the steering council. The steering council will be constituted of project contributors who have produced contributions that are substantial in quality and quantity, and sustained over moer than 4 weeks (the project is short-term, to be completed in less than a year). The overall role of the Council is to ensure, through working with the BDFL and taking input from the Community, the long-term well-being of the project, both technically and as a community.
The Council will have a Chair (hopefully other than @alfredoh1234 to avoid tunel-vision), who is tasked with keeping the organizational aspects of the functioning of the Council and the Project on track. The Council will also appoint a Release Manager (hopefully other than @alfredoh1234 to share workload) for the Project, who has final responsibility for one or more releases.
### Decision making
If it becomes necessary for the Steering Council to produce a formal decision, then they will use a form of the [Apache Foundation voting process](https://www.apache.org/foundation/voting.html). This is a formalized version of consensus, in which +1 votes indicate agreement, -1 votes are vetoes (and must be accompanied with a rationale, as above), and one can also vote fractionally (e.g. -0.5, +0.5) if one wishes to express an opinion without registering a full veto. These numeric votes are also often used informally as a way of getting a general sense of people’s feelings on some issue, and should not normally be taken as formal votes. A formal vote only occurs if explicitly declared, and if this does occur, then the vote should be held open for long enough to give all interested Council Members a chance to respond – at least one week.
In practice, we anticipate that for most Steering Council decisions (e.g., voting in new members) a more informal process will suffice.
When deciding on the model of governance to adopt, we looked at elements suggested by [Kimberly McClintock as available from Infoworld](https://www.networkworld.com/article/2204163/the-six-elements-of-open-source-governance.html):
| Elements | Description | Date reviewed | Date adopted |
|--------------|-------------|---------------|--------------|
|[Policies](#policies) | What is acceptable and what is not acceptable | (planned) Jun 30, 2020 | TBD |
|[Inventory](#inventory) | Not included, out of scope for this project | (planned) Jun 30, 2020 | TBD |
|[Managing](#managing) | How we plan to follow and enforce governance policies | (planned) Jun 30, 2020 | TBD |
|[Auditing](#auditing) | How we plan to monitor the respect of governance policies | (planned) Jun 30, 2020 | TBD |
|[Reporting](#reporting) | How we plan to communicate progress/status on governance | (planned) Jun 30, 2020 | TBD |
......@@ -75,15 +84,11 @@ For question regarding _Publication_ guidelines and policies on all aspects of I
For question regarding _Standards_ guidelines and policies for contributions-to or use-of IEEE intellectual property rights in Standards check the [IEEE Standards IPR](https://standards.ieee.org/ipr/index.html) webpage.
### Managing
Management of features, issues and improvements will be done through the [issue tracker](https://opensource.ieee.org/community/peer-review/admin/-/issues). There are three common decision making structures associated with self-governed open source projects according to [Dries Buytaert, InfoWorld](https://www.infoworld.com/article/3451796/3-models-for-open-source-governance.html):
* Benevolent Dictator For Life (Hierarchical): one person (project initiator or lead) has final say on all major project decisions; often, only this person commits code and appoints maintainers. The project's community contributes and reviews contributions.
* Meritocracy (Majority rule from decision-makers): active project contributors (those who demonstrate “merit”) are given a formal decision making role and decisions are usually made based on pure voting consensus. Contributions can only be made by individuals representing themselves, not by a company. All Responsibility is shared by community.
* Liberal contribution (Concensus): those doing the most (current) work are recognised as most influential. Major project decisions are made based on a consensus rather than pure vote, and include as many community perspectives as possible.
For this project, the BDFL model was adopted. @alfredo.herrera will be the only one making commits, but contributions to specific topics will be assigned to individual members of the committee who will provide a target date for completion of the task and self-direct the work.
Management of features, issues and improvements will be done through the [issue tracker](https://opensource.ieee.org/community/peer-review/admin/-/issues).
### Auditing
Auditing will be done on regular conference calls.
Auditing will be done during the regular conference calls:
* [Bi-weekly on Tuesdays 10h00 to 11h00 North-America Eastern time (Montreal) ](https://calendar.google.com/event?action=TEMPLATE&tmeid=b2FhMnM2cjBtdHZ0YmF2OXVhZXNoOXNtNTlfMjAyMDA3MjhUMTQwMDAwWiBhbGZyZWRvLmhlcnJlcmFAaWVlZS5vcmc&tmsrc=alfredo.herrera%40ieee.org&scp=ALL)
### Reporting
Following the regular conference call. A short summary will be posted in the [Minutes](https://opensource.ieee.org/community/peer-review/admin/-/tree/master/Minutes) directory with details recorded and tracked using issues.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment