Skip to content
This repository was archived by the owner on Jul 10, 2025. It is now read-only.

Commit e81f0f2

Browse files
ewilderjewilderj
authored
SIG and code governance docs (#10)
* Draft docs for SIG governance Change-Id: I59bf6f109b0c0cd44383c58fc853c8f9db26b4c5 * Draft docs for SIG governance Change-Id: Id4e62d95b284569bde503dcc5bb4341c1d61deff * Some refinements on templates Change-Id: I37f735b71e7a827f2916e40d348c02fd5748046b * Governance doc Change-Id: I5a15ccaf151ac70b963b77dd269abf1b0fc4f4f4 * Bring in footnotes Change-Id: I3b8ec7378ec691c57b76b5240ca7ae97dee15c3b * Fix bold text Change-Id: I9bb032a33d75638cb6612c290e2961311043510f * Readability improvements Change-Id: Ibff1b837ce261b25f5304206ed6ffa273579f019 * Revise comms language Change-Id: I36db6d89ec8b51fe70bef3a4332a7f4c7613396e * Fix line lengths Change-Id: I6aa31bedc59cb221b8c6cf675955971532456bcf * Rename SIG-charter.md to SIG-charter-template.md * Change name of charter template * Rename SIG-template.md to SIG-request-template.md * Update name of SIG request template
1 parent 61fca22 commit e81f0f2

File tree

4 files changed

+297
-0
lines changed

4 files changed

+297
-0
lines changed

‎governance/SIG-charter-template.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Proposed name: SIG-??????
2+
3+
## Objective
4+
5+
One or two sentences describing the group's purpose.
6+
7+
## Membership
8+
9+
*Who can join? How can they join? Who can read the group's activity?*
10+
11+
Example:
12+
13+
> Everyone involved in the packaging, distributing or embedding of TensorFlow is
14+
> welcome to join the group. To participate, request an invitation to join the
15+
> mailing list. Archives of the mailing list will be publicly accessible.
16+
17+
## Resources
18+
19+
*Links to essential resources: proposed mailing list, Github repo, key documents, etc.*
20+
21+
## Contacts
22+
23+
*Minimum highlight a group leader, and somebody to reach out to for
24+
administrative purposes*
25+
26+
* *Project lead: A N Other [@githubhandle](https://github.com/githubhandle) -
27+
another at companyname*
28+
* For administrative questions, contact Edd Wilder-James
29+
[@ewilderj](https://github.com/ewilderj) - ewj at google
30+
31+
## Code of Conduct
32+
33+
As with all forums and spaces related to TensorFlow, SIG-?????? is subject to
34+
the [TensorFlow Code of
35+
Conduct](https://github.com/tensorflow/tensorflow/blob/master/CODE_OF_CONDUCT.md).

‎governance/SIG-request-template.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Request for SIG
2+
3+
## What is this group for?
4+
5+
Describe the need the group fills. Who is the audience?
6+
Provide evidence that work is already ongoing in this area.
7+
8+
## Who will be part of it?
9+
10+
Describe:
11+
12+
* group leader
13+
* a second for the leader
14+
* one or more interested parties who will also be in the group -- provide
15+
evidence of the sustainability of the group
16+
17+
What will be your membership policy?
18+
19+
## What initial problems will the group tackle?
20+
21+
*List potential goals for the group*
22+
23+
## What modes of communication do you intend to use?
24+
25+
*A mailing list is a minimum. We recommend regularly scheduled VC calls to focus
26+
on agenda items. Slack or other chat channels are optional.*
27+
28+
## Launch plan
29+
30+
*Describe how the group will be launched. Example follows*
31+
32+
```
33+
1. `VC call with initial interested parties to finalize charter and initial group goals`
34+
1. `SIG set up with initial group members`
35+
1. `SIG added to community pages on tensorflow.org`
36+
1. `Write blog post about SIG and its goals`
37+
1. `Leader starts off mailing list discussion about initial work items`
38+
```
39+
40+
# Charter
41+
42+
Please draft the SIG's charter using the [SIG Charter Template](SIG-charter-template.md).
43+
44+

‎governance/SIGS.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# TensorFlow Special Interest Groups (SIGs)
2+
3+
## What makes a good SIG?
4+
5+
The ideal scope for a SIG will meet a well-defined domain, where the majority
6+
participation will be from the community. Additionally, there should be
7+
sufficient evidence that there are community members willing to engage and
8+
contribute should the interest group be established.
9+
10+
Not all SIGs will have the same level of energy, breadth of scope, or governance
11+
models, so we should expect some variability.
12+
13+
## Non-goals: What a SIG is not
14+
15+
The intent of a SIG is to facilitate collaboration on shared work. A SIG is
16+
therefore:
17+
18+
* **Not a support forum**: a mailing list and a SIG is not the same thing
19+
* **Not immediately required**: early on in a project's life, you may not know if you have shared work or collaborators
20+
* **Not free labor**: energy is required to grow and coordinate the work collaboratively.
21+
22+
Our approach to SIG creation will be conservative: thanks to the ease of
23+
starting projects on GitHub, there are many avenues where collaboration can
24+
happen without the need for a SIG.
25+
26+
## SIG playbook
27+
28+
### Research and consultation
29+
30+
Proposers of groups should gather evidence for approval, as specified below.
31+
Some possible avenues to consider are:
32+
33+
* A well-defined problem or set of problems the group would solve
34+
* Consultation with community members who would benefit, assessing both the
35+
benefit and their willingness to commit
36+
* For existing projects, evidence from issues and PRs that contributors care
37+
about the topic
38+
* Potential goals for the group to achieve
39+
* Resource requirements of running the group
40+
41+
Even if the need for a SIG seems self-evident, the research and consultation is
42+
still important to the success of the group.
43+
44+
### Creating the new group
45+
46+
The new group should follow the below process for chartering. In particular, it
47+
must demonstrate:
48+
49+
* A clear purpose and benefit to TensorFlow (either around a sub-project or
50+
application area)
51+
* Two or more contributors willing to act as maintainers, existence of other
52+
contributors, and evidence of demand for the group
53+
* Resources it will initially require (usually, mailing list and regular VC
54+
call.)
55+
56+
Approval for the group will be given by a decision of the TF Community Team,
57+
defined as being the maintainers of the _tensorflow/community_ project. The team
58+
will consult other stakeholders as necessary.
59+
60+
Before entering the formal parts of the process, it is advisable to consult with
61+
the TensorFlow community team, *[email protected]*. It is highly
62+
likely that conversation and iteration will be required before the SIG request
63+
is ready.
64+
65+
The formal request for the new group is done by submitting a charter as a PR to
66+
_tensorflow/community_, and including the request in the comments on the PR (see
67+
template below). On approval, the PR for the group will be merged and the
68+
required resources created.
69+
70+
### Template Request for New SIG
71+
72+
This template will be available in the community repo: [SIG-request-template.md](SIG-request-template.md).
73+
74+
### Chartering
75+
76+
Each group will be established with a charter, and be governed by the TensorFlow
77+
code of conduct. Archives of the group will be public. Membership may either be
78+
open to all without approval, or available on request, pending approval of the
79+
group administrator.
80+
81+
The charter must nominate an administrator. As well as an administrator, the
82+
group must include at least one maintainer as lead (these may be the same
83+
person), who will serve as point of contact for coordination as required with
84+
the TF community team.
85+
86+
This charter will be posted initially to the group mailing list. The _community_
87+
repository in the TensorFlow Github organization will archive such documents and
88+
policies ([example from Kubernetes](https://github.com/kubernetes/community)).
89+
As any group evolves its practices and conventions, we expect it to document
90+
these within the relevant part of the community repository.
91+
92+
### Collaboration and inclusion
93+
94+
While it is not mandated, the group should choose to make use of collaboration
95+
via scheduled conference call or chat channels to conduct meetings. Any such
96+
meetings should be advertised on the mailing list, and notes posted to the
97+
mailing list afterwards. Regular meeting helps drive accountability and progress
98+
in a SIG.
99+
100+
TensorFlow community team members will proactively monitor and encourage the
101+
group to discussion and action as appropriate.
102+
103+
### Launching
104+
105+
Required activities:
106+
107+
* Notifying TensorFlow general mailing lists (discuss@, developers ML) of new group
108+
* Adding SIG to the community pages on TensorFlow web site
109+
110+
Optional activities:
111+
112+
* Creating a blog post for the TensorFlow Medium.com blog community
113+
114+
### Health and termination of SIGs
115+
116+
The TF community team will make best effort to ensure the health of SIGs. From
117+
time to time it will request the SIG lead to provide a report of the SIG's work,
118+
which will be used to inform the broader TensorFlow community of the activity of
119+
the group.
120+
121+
If a SIG no longer has a useful purpose or interested community, it may be
122+
archived and cease operation. The TF community team reserves the right to
123+
archive such inactive SIGs, in order to maintain the health of the project at
124+
large, though it is a less preferable outcome. A SIG may also opt to disband if
125+
it recognizes it has reached the end of its useful life.

‎governance/code-and-collaboration.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
2+
# TensorFlow Governance: Code and Collaboration
3+
4+
## Projects
5+
6+
A **project** is the primary unit of collaboration. It can either have its own
7+
repo, or be a part of another repo (e.g. a directory in _tensorflow/models_).
8+
9+
10+
## Contributors
11+
12+
Anyone can submit a PR contribution to any project, as long as they have signed
13+
the CLA and follow the guidelines in
14+
[CONTRIBUTING.md](https://github.com/tensorflow/tensorflow/blob/master/CONTRIBUTING.md).
15+
Their code must be reviewed by a maintainer, and must pass all applicable tests.
16+
17+
Code reviews check for code quality and style, including documentation, and
18+
enforce API compatibility guarantees and other policies. Contributions may be
19+
rejected for strategic reasons unrelated to the code in question. For instance,
20+
because a feature may be too costly to maintain, or because it would duplicate
21+
APIs.
22+
23+
## Maintainers
24+
25+
A project has one or more **maintainers**.
26+
27+
Maintainers have write access to the repo containing their project. That means
28+
they can review PRs—an approving review will allow PRs to be merged. They can
29+
also change labels (which means they can trigger tests), add assignees and
30+
reviewers, and they can be assigned to issues and PRs.
31+
32+
Note that for some repos being a maintainer may not allow direct commit access,
33+
which is reserved for administrators or bots. *tensorflow/tensorflow* is a case
34+
in point, due to the complexity around releasing, only a small group of release
35+
engineers are administrators. In this case maintainers have approval rights.
36+
37+
If a repo is shared between many projects, we use GitHub's CODEOWNERS to
38+
identify owners and route PRs to them for review. Because of the way CODEOWNERS
39+
works, it is not possible to use the GitHub routing mechanism everywhere -- for
40+
example, the TensorFlow CODEOWNERS file is mainly for informational purposes, as
41+
to not impede merges.
42+
43+
Once there are more than a couple of maintainers for a project, we will create a
44+
GitHub team for the project maintainers. This allows for easier maintenance, and
45+
opens up some [GitHub
46+
tooling](https://help.github.com/articles/about-team-discussions/) for
47+
communication. Larger projects can facilitate coordination and contribution
48+
through establishing a
49+
[TensorFlow SIG](SIGS.md).
50+
51+
52+
### Repositories requiring synchronization
53+
54+
For some projects initiated by Google (including the _tensorflow/tensorflow_
55+
repo), the infrastructure which synchronizes and merges internal and external
56+
changes requires that all merges are performed by a Google employee. In such
57+
cases, Google sets up an on-call rotation which merges PRs once they pass tests
58+
(and a specific label is applied to the PR in order to notify the rotation to
59+
merge it). This does not preclude non-Google contributors from becoming
60+
maintainers. In this case, the maintainers of the project decide on what should
61+
be merged, then the actual merging is performed as a service. In some cases,
62+
Google-internal tests may fail and may have to be fixed: the Google employee
63+
will work with the submitter to achieve this.
64+
65+
66+
### Achieving maintainer status
67+
68+
Maintainers may elevate a contributor to maintainer status, on evidence of
69+
previous contributions and established trust.
70+
71+
## Collaboration
72+
73+
Maintainers are free to agree on their preferred form of collaboration and
74+
decision making, with the requirement that regular communication about decisions
75+
must be made publicly accessible—this can happen after the fact, for example in
76+
the form of publishing meeting minutes, reviews, or announcements. Communication
77+
about topics such as admitting other maintainers, or as of yet undisclosed
78+
security issues, can be kept confidential.
79+
80+
If significant engagement from multiple parties is encountered, the group may
81+
request the formation of a SIG to formalize collaboration and cooperation. The
82+
threshold for SIG formation includes:
83+
84+
* A clearly stated purpose
85+
* Two or more non-maintainers willing to contribute code, and evidence of
86+
existing demand for the group
87+
* Project maintainers willing to be in the group and shepherd contributions
88+
89+
For further details on SIGs, read [TensorFlow SIGs](SIGS.md).
90+
91+
As with most structures, a project doesn't need a SIG to get started, but should
92+
find a home in one if it has proven itself as an ongoing concern, as SIGs are
93+
the primary organizational vehicle for the contributor community.

0 commit comments

Comments
 (0)