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

CONTRIBUTING.md 10.3 KB
Newer Older
Alfredo Herrera's avatar
Alfredo Herrera committed
1 2 3 4
Copyright (C) 2020 IEEE SA OSCom, peer-review ad-hoc subcommittee un der the terms of the [Apache Licence Version 2](https://opensource.ieee.org/community/peer-review/admin/-/blob/master/LICENSE).

Contributing to IEEE SA OSCom open-source peer-review ad-hoc sub-committee project
===
Alfredo Herrera's avatar
Alfredo Herrera committed
5

Alfredo Herrera's avatar
Alfredo Herrera committed
6
###### Attribution
Alfredo Herrera's avatar
Alfredo Herrera committed
7 8 9 10
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. 
Alfredo Herrera's avatar
Alfredo Herrera committed
11

Alfredo Herrera's avatar
Alfredo Herrera committed
12
## Contents
Alfredo Herrera's avatar
Alfredo Herrera committed
13 14
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:
Alfredo Herrera's avatar
Alfredo Herrera committed
15
- [Issues and bug reports](#issues-and-bug-reports)
Alfredo Herrera's avatar
Alfredo Herrera committed
16
- [Contributing to document](#contributing-to-document)
17
- [Decision Making and Governance](#decision-making-and-governance)
Alfredo Herrera's avatar
Alfredo Herrera committed
18

Alfredo Herrera's avatar
Alfredo Herrera committed
19
## Issues and bug reports
Alfredo Herrera's avatar
Alfredo Herrera committed
20 21
If you believe that you have found a _bug or error_, we would like to know about it!
- To report a bug or error, please raise an issue on the
Alfredo Herrera's avatar
Alfredo Herrera committed
22
  **[issue tracker](https://opensource.ieee.org/community/peer-review/admin/-/issues)** -- be
Alfredo Herrera's avatar
Alfredo Herrera committed
23
  sure to do a quick search and see if anyone has reported the same thing before to avoid duplication.
Alfredo Herrera's avatar
Alfredo Herrera committed
24
- 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)
25

Alfredo Herrera's avatar
Alfredo Herrera committed
26
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.
Alfredo Herrera's avatar
Alfredo Herrera committed
27

Alfredo Herrera's avatar
Alfredo Herrera committed
28
## Contributing to document
Alfredo Herrera's avatar
Alfredo Herrera committed
29
If you would like to contribute improvements or add new topic/feature, please consider contributing it to the project following this simple process:
Alfredo Herrera's avatar
Alfredo Herrera committed
30

Alfredo Herrera's avatar
Alfredo Herrera committed
31 32
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.
2. Once in your project space, create a branch using this recommended naming convention:
Alfredo Herrera's avatar
Alfredo Herrera committed
33 34
   - `feature/myawesomebranch`: a new feature that wasn't in Peer-Review already.
   - `fix/mygreatfix`: fixes an issue that isn't tracked in the issue tracker.
Alfredo Herrera's avatar
Alfredo Herrera committed
35 36
   - `issue###/123-myfantasticpatch`: fixes an issue that is tracked in the issue tracker (please replace `###` with the issue number)
   - `tidy/mybrillianttidying`: cosmetic fixes to bring existing files up to the [formatting guidelines](#formatting-guidelines) defined below.
Martin Haeuer's avatar
Martin Haeuer committed
37
3. Submit a merge request to merge back into the [`opensource.ieee.org/community`](https://opensource.ieee.org/community/) project space. ___Note:___ If you are merging back just to see the difference between your change and the project space code, use the `[WIP]` text at the begining of the title of your merge request: this convention will signal to us to disregard the merged request but to keep it for your viewing.
Alfredo Herrera's avatar
Alfredo Herrera committed
38 39
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.
Alfredo Herrera's avatar
Alfredo Herrera committed
40

Alfredo Herrera's avatar
Alfredo Herrera committed
41 42
### 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:
Alfredo Herrera's avatar
Alfredo Herrera committed
43
- Be concise.
Alfredo Herrera's avatar
Alfredo Herrera committed
44
- Limit the numer of references to external resources (external to the repostory).
Alfredo Herrera's avatar
Alfredo Herrera committed
45 46
- Be thorough.
- Use simple gramatical constructs.
Alfredo Herrera's avatar
Alfredo Herrera committed
47

48
## Decision making and Governance
Alfredo Herrera's avatar
Alfredo Herrera committed
49 50 51 52 53 54 55 56 57 58 59
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):
60 61 62 63 64 65 66 67

|   Elements   | Description | Date reviewed | Date adopted |
|--------------|-------------|---------------|--------------|
|[Policies](#policies)   | What is acceptable and what is not acceptable             | (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      |

Alfredo Herrera's avatar
Alfredo Herrera committed
68 69
Decision making will be based on [SciPy's governance](http://scipy.github.io/devdocs/dev/governance/governance.html).

70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86
### Policies
We adhere to [IEEE's code of conduct](https://www.ieee.org/content/dam/ieee-org/ieee/web/org/about/ieee_code_of_conduct.pdf), we count on you to follow it in all your interactions within the project:
  1. Be respectful of others
  2. Treat people fairly
  3. Avoid injuring others, their property, reputation or employment
  4. Refrain from retaliation
  5. Comply  with  applicable  laws  in  all  countries  where  IEEE  does  business  and  with  the  IEEE policies and procedures

Instances of abusive, harassing, or otherwise unacceptable behavior shall be reported to [supportcenter@ieee.org](mailto:supportcenter@ieee.org). 

Reports of violations, or concerns regarding potential violations, of IEEE Policies or the IEEE Code of Conduct can be filed anonymously through EthicsPoint at +1 (888) 359-6323 or by [submitting an online report](https://secure.ethicspoint.com/domain/en/report_custom.asp?clientid=20410).

For question regarding _Publication_ guidelines and policies on all aspects of IEEE intellectual property rights for authors, readers, researchers, and volunteers check the [IEEE Publications IPR](https://www.ieee.org/publications/rights/index.html) webpage.

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
Alfredo Herrera's avatar
Alfredo Herrera committed
87
Management of features, issues and improvements will be done through the [issue tracker](https://opensource.ieee.org/community/peer-review/admin/-/issues). 
88 89

### Auditing
Alfredo Herrera's avatar
Alfredo Herrera committed
90 91
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)
92 93 94 95 96

### 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.