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

Commit cc21a6c8 authored by IEEE SA OSCM's avatar IEEE SA OSCM
Browse files

Merge branch 'oscom-approved' into 'master'

Release of version 1.0.0-rc.1

See merge request !10
parents 56313729 e0d1d716
## Policy, Ethics, and Code of Conduct
IEEE supports open source as one method for consensus development
within its portfolio of collaborative activities. Your participation
as a Leader, Maintainer, or Contributor of any IEEE Open Source
Project and/or your use of the IEEE Open Source Platform is contingent
upon, although not limited to, your agreement to comply with this
manual, the IEEE SA OPen Source Committee Operations Manual, and the
following:
<details>
<summary>All applicable IEEE policies and procedures, including but not limited to:</summary>
* [IEEE Code of Conduct](https://www.ieee.org/content/dam/ieee-org/ieee/web/org/about/ieee_code_of_conduct.pdf)
* [IEEE Code of Ethics](https://www.ieee.org/about/corporate/governance/p7-8.html)
* [IEEE Terms and Conditions](https://www.ieee.org/site-terms-conditions.html?WT.mc_id=hpf_terms&utm_source=hp&utm_campaign=hpf_terms&utm_medium=hpf&utm_term=terms%20conditions)
* [IEEE Nondiscrimination Policy](https://www.ieee.org/about/corporate/governance/p9-26.html](https://www.ieee.org/about/corporate/governance/p9-26.html)
* [IEEE Principles of Business Conduct and Conflict of Interest](https://www.ieee.org/about/compliance/conflict-of-interest/index.html)
* [Compliance Related IEEE Policies](https://www.ieee.org/content/dam/ieee-org/ieee/web/org/about/whatis/ieee_policies.pdf), including:
* Anti-Boycott Policy (§12.12)
* Anti-Bribery and Corruption Policy (§12.13)
* Antitrust and Fair Competition Policy (§12.10)
* Civility Policy (§9.25)
* Computer Policy (§9.28)
* Economic Sanctions and Embargoes Policy (§12.11)
* IEEE Records Management Policy Statement (§12.8)
* IEEE Social Media Policy (§9.27)
* Whistleblower and Non-Retaliation Policy (§9.9)
* Remain consistent with definitions of Bullying, Discrimination, Harassment, Retaliation (unumbered front matter text)
</details>
<details>
<summary>CLAs and Preserve Appropriate Legal Notices </summary>
* Submit any applicable
[IEEE Contributor License Agreement](https://opensource.ieee.org/community/cla](https://opensource.ieee.org/community/cla) (CLA) where required by specific IEEE Open Source Projects.
* Post and preserve any and all appropriate legal notices (e.g.,
copyright and license file headers) where the license or relevant
IEEE policy requires.
</details>
<details>
<summary>CLAs and Preserve Appropriate Legal Notices </summary>
* Submit any applicable
[IEEE Contributor License Agreement](https://opensource.ieee.org/community/cla](https://opensource.ieee.org/community/cla) (CLA) where required by specific IEEE Open Source Projects.
* Post and preserve any and all appropriate legal notices (e.g.,
copyright and license file headers) where the license or relevant
IEEE policy requires.
</details>
<details>
<summary>In addition we recommend that you adhere to the following terms: </summary>
We recommend that all individuals involved in the design and
development of autonomous and intelligent systems as part of their
participation in an IEEE Open Source Project to strive to be educated,
trained, and empowered to prioritize ethical considerations in the
design and development of autonomous and intelligent systems. The
[IEEE Global Initiative for Ethical Considerations in Artificial
Intelligence and Autonomous
Systems](http://standards.ieee.org/develop/indconn/ec/autonomous_systems.html)
supports those seeking ot satisfy this recommendation; the
Initiative's mission statement is as follows:
> To ensure every stakeholder involved in the design and development of
> autonomous and intelligent systems is educated, trained, and empowered
> to prioritize ethical considerations so that these technologies are
> advanced for the benefit of humanity.
</details>
<details>
<summary>Ethics and Compliance Helpline</summary>
Reports of violations, or concerns regarding potential violations, of
IEEE Policies or the IEEE Code of Conduct can be filed anonymously
through EthicsPoint:
* :telephone_receiver: Call the 24-hour phone number: +1(888)359-6323
* :computer: [Submit an online report](https://secure.ethicspoint.com/domain/en/report_custom.asp?clientid=20410)
</details>
\ No newline at end of file
## Setting up an Official IEEE Open Source Project
Your Official IEEE Open Source Project may contain one or more
projects on opensource.ieee.org. Each project should contain the
following files in the project's git repository:
* README.md - Info about your project (see below for more detailed example)
* LICENSE - A copy of the project's license; this should be taken from the appropriate license file in https://opensource.ieee.org/community/cla/licenses
* AUTHORS.md - A list of copyright holders
* CONTRIBUTORS.md - A list of contributors
Additional files you may want to have or may need to have:
* NOTICES.md - Additional legal notices
* contributing.md - Policies for how you would like to accept contributions
* security.md - Policy on how to handle CVEs
## README
Your project's README file should provide at minimum information about
your project, how to contribute (including license/CLA info), and a
list of the project's lead(s) and/or maintainer(s). Some additional
sections and info are recommended. Below is a list of various
recommended sections.
Also, have fun. Use emoji. Be friendly and welcoming.
### Detail contents of a simple README file
* :mag_right: About
* 1-2 paragraphs describing the purpose of the project
* License
```
All source code files in this repository are subject to the following copyright and licensing terms.
Copyright 2020 NAME or GROUP-NAME
See the LICENSE file distributed with this work for copyright and
licensing information, the AUTHORS file for a list of copyright
holders, and the CONTRIBUTORS file for the list of contributors.
```
* :checkered_flag: Getting Started
* :hammer_and_wrench: Requirements or preconditions needed to install the software or any assumptions.
* :page_with_curl: Instructions (step-by-step guide) to get a copy of the project up and running on a peron's local machine for use, development, and/or testing.
* Usage - any additional usage notes on using the software
* :unicorn: Project leadership
* Project Lead (username)
* Project maintainer name (username)
* :gift: Contributing
* This project is licensed under the terms of the (LICENSE NAME). Contributions are accepted under a Contributor License Agreement (LINK to appropriate project https://opensource.ieee.org/community/cla/). See (LINK to contributing.md) for more
* :speech_balloon: Communicating
* Link to any mailing list
* Link to public mattermost channel
* :tada: Acknowledgements
* See CONTRIBUTORS.md for a list of contributors and AUTHORS.md for a list of authors.
* Any additional thanks, etc. you wish to add (e.g., another project that provided inspiration, etc).
This diff is collapsed.
## Quick Start
### Who is needs to read the Maintainers Manual?
:pushpin: Maintainers and Leads of an IEEE Open Source Projects shall (**must**) follow all requirements contained in this manual.
All other users of the IEEE Open Source Platform should follow recommendations and the recommended templates and may benefit from the examples and suggestions throughout.
### What are the requirements?
:bulb: Click on the "▸" and expand the section. Click again to collapse. :bulb:
<details>
<summary>Click to expand!</summary>
## Heading
1. A numbered
2. list
* With some
* Sub bullets
</details>
### About IEEE
* IEEE is the world’s largest technical professional organization dedicated to advancing technology for the benefit of humanity.
* Mission: IEEE's core purpose is to foster technological innovation and excellence for the benefit of humanity.
* Vision: IEEE will be essential to the global technical community and to technical professionals everywhere, and be universally recognized for the contributions of technology and of technical professionals in improving global conditions.
*
* This Maintainers Manual is approved by the Open Source Committee of the IEEE SA Board of Governors.
as well as recommendations, and guides fo
* The *Maintainers Manual* contains requirements ("shalls"/"musts"), recommendations ("shoulds"), and , and suggestionsguidelines and advice for someone who is the maintainer This is the the *Maintainers Manual* for IEEE Standards Association Open Source
* policy requirements for leads and maintainers
## Introduction
Whether you are a person downloading a socail app to your phone, a
developer building on top of the next great aschynchronous runtime
library, or a maker bringing a design document to fabrication of your
new IoT gizmo, in each situation, you will almost always be able to
determine quickly and unambiguously whether or not a self-contained
(single-sourced) app, library, or design document you have downloaded
is an open source work. In practice, you can tell if something is an
open source work by simply checking to see if the source code and/or
design documents are made available to you under the terms of an open
source license.
However, the matter can quickly get complex
However, when you are helping to create open source software and
hardware, or you are seeking ot provide support and guidance for the
growth of many new open source communities, a more general definition
to go alongside the licensing terms is essential. The IEEE Standards
Association Open Source Committee Operations Manual provides the
following definition of open source for use by our communities:
> **Open Source** is a digital work for which the human-readable
> source code is available—in the preferred form for making
> modifications—for use, study, re-use, modification, enhancement, and
> re-distribution by the users. Open Source applies to software and
> hardware, which may include computer code, hardware designs, data,
> documentation, documents, and other digital objects.
However, when it comes to nurturing, growing, and sustaining open
source projects, communities, and ecosystems, then open source
software & hardware is more than just licensed source code files, it
is also: open source is also project planning and management; is also
project management, and governance; it is massively distributed,
collaborative development; it is shipping a product to users or
adopters of your work and developing a trusted relationship with them.
The IEEE SA provides a platform of
As a user of opensource.ieee.org, we have granted to you the ability to be If you are a Lead or Maintainer of a project hosted on [opensource.ieee.org](https://opensource.ieee.org),
Similarly, the IEEE SA offers a platform for users, contributors, support for communities to come and collaborate open source, and so we too are seeking to
As a Lead or Maintainer of a project hosted on the <https://opensource.ieee.org>, it is essential that you follow
For Leads and Maintainers of open source projects, eaders and maintainers of open source projects, it is often about
fostering a community of users and contributors.
The purpose of this manual is to:
*
If you are (or are thinking of becoming) a Lead or a Maintainer of an
open source project hosted on <https://opensource.ieee.org>, then this
manual is required reading. Wherever possible we will do our best to
indicate clearly any requirements we ask you to follow (we will use
terms such as "shall" and "must").
### Contents
This is copy of our internal open source documentation, with a few
exceptions. For a number of reasons, we can't share everything, so you
might find places where a link is missing or some content had to be
removed.
Aside from those few cases, this is the same documentation seen by
Google employees. As a result, there is some Google lingo throughout,
as well as references to internal tools and systems. See the glossary
for definitions of some of the most common ones.
There are three primary sections of the docs:
Creating covers how Googlers release code that they've written, either
in the form of a new standalone project or as a patch to an external
project. The same process is used for small 20% projects and full
blown Google projects.
Using explains how we bring open source code into the company and use
it to help build great products. We carefully catalog thousands of
packages to help us maintain license compliance.
Growing describes some of the programs we run inside and outside the
company to support open source communities.
Who this is for
###
### About IEEE SA Open Source
## Contributors (“engineers”)
IEEE Public (e.g. companies wanting to know how the platform is governed and works …)
### Front Matter and intro
### Scope and Purpose of the Manual
Executive summary .5 page.
* The role and responsibility of the maintainer in the IEEE Open Source environment
* Who needs this (maintainers of group and individual projects)
* Scope & Purpose statement - to document roles and responsibilities and applicable policies.
### Scope and Purpose of the Platform
* Positioning: IEEE Open as a philosophy [Link to Marketing Materials when available, not a blocker] [
* Types of IEEE Open Source Projects [Include and explain]
* Supporting the wider open source community [ included in marketing, not a blocker]
* Access to technical expertise
* Open Source planning, dev, testing, communication tools
* Supporting open consensus standards that incorporate open source [Merge with descriptions of types of projects above]
* Software
* Hardware
* Entire standard as open source
Resources for Maintainers
* Community / IP manager
* Platform resources
* Issue reporting
* (Continuous integration)
* (Peer Review mention)
#### IEEE Open Source Governance
[Roles and responsibilities are in previous section]
[Details are in following sections]
[Governance documents have already been agreed]
Summary of how IEEE governs Open Source
Creating a governance document (see Ops Man 5.1.2 for what needs to be covered)
Samples / Templates… TBD (Group / Official / Standards)
### Account and Group Management
(May separate out things only applicable to group namespaces)
Cross-reference table (individual / group / official / standards)
* Adding users to a project
* Assigning project roles to users
* Granting access
* Creating a project- approvals (if needed)
* Name, description, README file
* LICENSE (choose Apache 2.0 or BSD 3-clause)
* Collaboration responsibilities
* Have fun! glhf
* Responsibilities when you fork a project
* Mattermost / Slack
* List of governance documents
Publicizing your project [ Not clear where this goes but we want to tell maintainers how to access resources for publicizing projects]
### Running a project
* What Leaders and Committers do [links to appropriate policy documents]
* Responsibilities of Maintainers
* Following policies and procedures
* Following additional IEEE agreements (standards, fiscal sponsorship, etc)
* Representing your project and the IEEE outside of the Platform
* Delegating responsibility and access control
* Communicating with OSCM, OSCom, IPR Manager
* Community governance
* Leadership changes
* Configuration Management
* Version control, version (semantic) numbering *within your own project* [once forked, new maintainer - could by you], submodules
* Validation, scanning, and enforcement of CLAs (e.g. responding to alerts) [understanding what they must do to maintain legal notices etc.]
* (later) Peer review and testing -- notice that it is planned, link to OSCom OpsMan
* Aim of peer review
* under development (SIG needed)
[Maybe under release management]
* Release Management
* Mandatory coordination with OSCM
* Official vs unofficial releases [official projects shall designate which releases are official] [blocking issue]
* Signed releases (PGP signing) [should not block MVM]
* Backport (and security) patching [should not block MVM]
* Mirroring and archiving releases [should not block MVM]
* Documentation requirements for open source that is incorporated into standards (including short description of what the software does, how to install it, plus stuff Josh said.)
* Issue problem management
* Creating, assigning, tagging, and managing issues [IT IS REQUIRED THAT MAINTAINERS RESPOND TO SOME TYPES OF ISSUES]
* Email/helpdesk use of issues [should not block MVM]
* Standards considerations
* Roles and responsibility of Standards Committee and WG with OS project - [covered in SASB Ops Man so summarize and link]
* Balloting (see process points document) [covered in SASB Ops Man so summarize and link, need to explain the workflow and how it works]
* Comment resolution group
* Comments made as issues versus ballot comments
* Ballot comments that address open source artifacts (e.g. code) - c.f. The need for a CLA
* Notices [Required notice that it is not an approved standard in the read.me file]
* Interactions with WG (copy/paste other WG guidance?)
### Retiring a group or project [put in, but not a blocker]
* Update README file and CONTRIBUTING/GOVERNANCE files
* Archive project (or request that OSCM archives project)
* Retiring a group requires agreement among all leadership and approval by IEEE Staff
* Email OSCM
* Special considerations for standards projects
### Licensing policies [blocker]
* CLAs and choice of license
* Use of third-party material and dependency management
* Naming, Branding, Trademark, and Tradename
### Security policies [next]
* Minimum requirements:
* Official IEEE Open Source Projects (including standards that incorporate Official IEEE Open Source Projects) _may_ be required to follow our Security policy?
* IEEE Open Source Projects are able to opt-in
* Responsibilities under policies
* Release and CVE
* Notice that the IEEE may scan all repositories on the IEEE Open Source Platform?
Shall have SVE process for official releases of official / standards projects
Should have SVE process for group projects
May have for individual
\ No newline at end of file
Disclaimer
This open source repository contains material that may be included-in
or referenced by an unapproved draft of a proposed IEEE Standard. All
material in this repository is subject to change. The material in this
repository is presented "as is" and with all faults. Use of the
material is at the sole risk of the user. IEEE specifically disclaims
all warranties and representations with respect to all material
contained in this repository and shall not be liable, under any
theory, for any use of the material. Unapproved drafts of proposed
IEEE standards must not be utilized for any conformance/compliance
purposes.
## TODO
* Create <opensource-security@ieee.org>
* Determine how we will obtain CVE numbers
We encourage you to use the SECURITY.md template we have provided for you.
Below is our recommended security process which you may be required to
follow if your project has been deemed as needing a formal security
reporting process.
## Security process
All projects on the IEEE Open Source Platform that have been deemed as needing
a formal security reporting process are required to have a SECURITY.md file
in the root directory of their project's repository and to follow the following
seucirty process (or an alternative security process approved by the
Open Source Committee and approved for use by your project).
1. Security vulnerabilities are reported to <opensource-security@ieee.org>. Security reports are confidential.
2. The Open Source Community Manager will contact the *security
contact* listed by the Official IEEE Open Source Project and ensure
that the security vulnerability is reviewed to determine if it is
accepted or rejected. You may choose to list the maintainer that is
the appropraite security contact on your project (such as in your
SECURITY.md page) or you may provide the contact (or list of
contacts) to the Open Source Community Manager to maintain
privately.
3. The Open Source Community Manager will notify the reporter if their
report has been accepted or rejected
4. If a report is accepted the following protocol shall be followed:
a. The Open Source Community Manager will determine if a CVE number should be obtained, and if so, IEEE shall obtain a CVE number.
b. The project will patch the vulernability and stage a release and draft a short announcement that includes the CVE number, severity, and impact.
c. The Open Source Community Manager will review the release and
announcement and coordinate to schedule a date and time for
public releaes. At this time, your project may discuss with the
Open Source Community Manager any private disclosures you wish to
make in advance of the public disclosure, such as to the reporter
of the vulernability or to any identified stakeholders. The Open
Source Community Manager will only deny requests if there are any
suspicion that permitting such a request would violate IEEE
Policy or if the private disclosure would in effect be equivalent
of making a public disclosure.
d. The release shall be made as it normally would, but without
disclosing that it is patching a security vulnerability.
e. The release shall be timed so that a release announcement will be
sent out to immediately after the release. The announcement shall
go out to all relevant security announcement mailing lists as
well as any external security lists or portals the Open Source
Community Manager deems appropriate (e.g.,
oss-security@lists.openwall.com).
5. If a report is accepted and this project is also an IEEE Standard
that incorporates an IEEE Open Source Project, then the additional
standards protocol will be followed as well.
a. If the project is incorporated through an undated/unversioned
reference, then the above protocol suffices with the caveat that
there may be additional mailing list or forums where the
announcement will be posted.
b. If the project is incorporated through a versioned reference,
then it must be determined if it is an errata or corrigenda. If
it is an errata, the above protocol shall be followed with the
announcement timed to coincide with the errata. If a corrigenda
is required, then the above protocol shall be followed and the
corrigenda process shall be followed after the announcement is
made, and additional notices shall be placed on apporpriate
places warning users about the issue.
## TODO
* Create <opensource-security@ieee.org>
* Determine how we will obtain CVE numbers
You may choose to adapt our standard template or to construct your own
security process documentation. In all cases, your documentation
should be inline with the following process.
## Security Reporting
If you wish to report a security vulnerability -- thank you! -- we ask
that you follow the following process, which complies with the Open
Source Committee Maintainers Manual.
Please fill out the following template:
Please report security vulnerabilities by filling out the following template:
* PROJECT: A URL to project's repository
* PUBLIC: Please let us know if this vulnerability has been made or discussed publicly already, and if so, please let us know where.
* DESCRIPTION: Please provide precise description of the security vulnerability you have found with as much information as you are able and willing to provide.
Please send the above info, along with any other information you feel
is pertinant to: <opensource-security@ieee.org>.
In addition, you may request that the project provide you a patched
release in advance of the release announcement, however, we can not
gaurantee that such information will be provided to you in advance of
the public release and announcement. However ,the Open Source
Community Manager will email you at the same time the public
announcement is made.
The IEEE SA Open Source Community Manager will let you know within two
business weeks whether or not your report has been accepted or
rejected. We ask that you please keep the report confidential until we
have made a public announcement.
Place this file in the top level of your project's git repo and rename it "README.md"
# Project Title
One paragraph short description
## License
All source code files in this repository are subject to the
following copyright and licensing terms.
Copyright 2020 NAME or GROUP-NAME
See the LICENSE file distributed with this work for copyright and
licensing information, the AUTHORS file for a list of copyright
holders, and the CONTRIBUTORS file for the list of contributors.
## Contributing
Please read [CONTRIBUTING.md].
## Getting Started
* git clone https://opensource.ieee.org/example/example.git
> *Alternatively, if your repository uses submodule then provide*
> *instructions along these lines*
> For a repo with submodules, we can pull all submodules using
>
> git submodule update --init --recursive
> for the first time. All submodules will be pulled down locally.
>
> To update submodules, we can use
>
> git submodule update --recursive --remote
> or simply
> git pull --recurse-submodules
### Prerequisites
What things you need to install the software and how to install them
```
Give examples
```
### Installing
A step by step series of examples that tell you how to get a
development env running
```
Step through
```
1. Step one
2. Step two
3. Step three, etc