Skip to content

Commit 3168e35

Browse files
bciprianobcipriano
authored
Sync content from and remove references to CONTRIBUTING.md. (#194)
1 parent b3083ff commit 3168e35

File tree

5 files changed

+104
-90
lines changed

5 files changed

+104
-90
lines changed

‎CONTRIBUTING.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
## Contribution guidelines
22

33
So, you want to contribute to the OpenCue web site? To find out how you can help, refer to OpenCue's overall
4-
[contribution guidelines](https://github.com/AcademySoftwareFoundation/OpenCue/blob/master/CONTRIBUTING.md).
4+
[contribution guidelines](https://www.opencue.io/contributing/opencue/contributing/).

‎README.md

+2-3
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,8 @@ run, to propose changes to the OpenCue documentation.
1414
### Before you begin
1515

1616
To learn about the process for contributing to OpenCue, see
17-
[Contributing to OpenCue](https://github.com/AcademySoftwareFoundation/OpenCue/blob/master/CONTRIBUTING.md)
18-
on the primary OpenCue repository. This page provides additional help and
19-
information about contributing to the OpenCue documentation.
17+
[Contributing to OpenCue](https://www.opencue.io/contributing/opencue/contributing/). This page
18+
provides additional help and information about contributing to the OpenCue documentation.
2019

2120
As with all changes to OpenCue, you also need to be familiar with common Git
2221
workflows.

‎content/_index.html

+1-1
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ <h1>What is OpenCue?</h1>
6565
Join the OpenCue [discussion forum](https://lists.aswf.io/g/opencue-user) for users and admins.
6666
{{% /blocks/feature %}}
6767

68-
{{% blocks/feature icon="fab fa-github" title="Contributions welcome!" url="https://github.com/AcademySoftwareFoundation/OpenCue/blob/master/CONTRIBUTING.md" %}}
68+
{{% blocks/feature icon="fab fa-github" title="Contributions welcome!" url="/contributing/opencue/contributing/" %}}
6969
Want to contribute to OpenCue? New users are always welcome!
7070
{{% /blocks/feature %}}
7171

‎content/contributing/opencue/contributing.md

+100-61
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,14 @@
11
---
22
title: "Contributing to OpenCue"
33
linkTitle: "Contributing to OpenCue"
4-
date: 2019-07-25
4+
date: 2020-05-04
55
weight: 1
66
description: >
77
Contribute to OpenCue development
88
---
99

1010
<!---DO NOT MODIFY THIS LINE--->
1111

12-
<!---The contents of page published at
13-
https://www.opencue.io/contributing/opencue/contributing/ is single sourced
14-
from the CONTRIBUTING.md file in the OpenCue repository. To suggest suggest
15-
changes to this content, send a pull request for the file at
16-
https://github.com/AcademySoftwareFoundation/OpenCue/blob/master/CONTRIBUTING.md--->
17-
1812
Code contributions to OpenCue are welcome! Please review this document to get
1913
a briefing on our process.
2014

@@ -71,30 +65,42 @@ the upstream OpenCue repository. These topics are covered in
7165
[Cloning a repository](https://help.github.com/articles/cloning-a-repository/)
7266
and
7367
[Configuring a remote for a fork](https://help.github.com/articles/configuring-a-remote-for-a-fork/),
74-
but again, if you need assistance feel free to reach out on the ocio-dev mail
75-
list.
68+
but again, if you need assistance feel free to reach out on the
69+
[opencue-dev mail list](https://lists.aswf.io/g/opencue-dev).
7670

77-
## Contributor License Agreement (CLA) and Intellectual Property
71+
## GitHub Issues
7872

79-
To protect the project -- and the contributors! -- we do require a
80-
Contributor License Agreement (CLA) for anybody submitting changes.
73+
OpenCue tracks outstanding and in-progress work through
74+
[GitHub Issues](https://guides.github.com/features/issues/).
8175

82-
* If you are an individual writing the code on your own time and you're SURE
83-
you are the sole owner of any intellectual property you contribute, you'll
84-
want to sign the Individual CLA.
76+
You can view a list of existing issues on the
77+
[OpenCue issues page](https://github.com/AcademySoftwareFoundation/OpenCue/issues).
8578

86-
* If you are writing the code as part of your job, or if there is any
87-
possibility that your employers might think they own any intellectual
88-
property you create, then you should use the Corporate CLA.
79+
Before you start writing code, make sure that you have a GitHub issue
80+
assigned to you which describes the work you plan to do. Feel free to file
81+
a new issue if one doesn't exist for that work, but please search the existing
82+
issues list first to avoid filing a duplicate.
8983

90-
Our CLAs are based on those used by Apache and many other open source
91-
projects.
84+
Having an assigned issue serves a few purposes:
9285

93-
Every pull request runs a check using the Linux Foundation's CLA tool
94-
to verify that all committers have signed the CLA. If you haven't,
95-
the pull request's status check will display the next steps you should
96-
take. You'll log into the CLA tool which will walk you through the
97-
process.
86+
- Avoids duplicating work. You may find that your planned issue is already
87+
being worked on by someone else! If an issue has an existing assignee,
88+
coordinate with them to find out the current state of their work and if
89+
you can assist. If you don't get a response, or the issue seems to be stale,
90+
reach out to a [Code Owner](./CODEOWNERS) to escalate.
91+
92+
- Provides a centralized place to track related work. There may be related
93+
discussion, and many issues are complex enough to require more than one
94+
pull request to be fully resolved. The issue page provides a home for
95+
all of that material, which is very helpful for future contributors to
96+
look back on.
97+
98+
- Helps us populate our release notes. Published
99+
[OpenCue releases](https://github.com/AcademySoftwareFoundation/OpenCue/releases)
100+
use Github issue or pull request numbers to identify what has changed in
101+
each release.
102+
103+
Nearly all pull requests should have an issue associated with them.
98104

99105
## Development and Pull Requests
100106

@@ -107,41 +113,73 @@ The development cycle for a code change should follow this protocol:
107113
1. Create a topic branch in your local repository.
108114

109115
2. Make changes, compile, and test thoroughly. Code style should match existing
110-
style and conventions, and changes should be focused on the topic the pull
111-
request will be addressing. Make unrelated changes in a separate topic branch
112-
with a separate pull request.
116+
style and conventions, and changes should be focused on the topic the pull
117+
request will be addressing. Make unrelated changes in a separate topic branch
118+
with a separate pull request.
113119

114120
3. Push commits to your fork.
115121

116122
4. Create a Github pull request from your topic branch. This can be
117-
a normal pull request or a **draft** pull request:
123+
a normal pull request or a **draft** pull request:
118124

119125
- Normal pull request: Use this if you feel like your change is
120126
ready to be merged or close to that. Reviews will be automatically
121127
requested from all of our Code Owners, but feel free to add others
122128
if you'd like -- we love to get as much feedback as we can!
123-
129+
124130
- Draft pull request: Use this if you feel like your change isn't
125131
ready to be merged -- maybe it's just an idea you have -- but
126132
you want feedback anyway. Reviews will not be automatically
127133
requested, but feel free to add reviewers anyway and we'll be happy
128134
to provide feedback -- [CODEOWNERS](./CODEOWNERS) is a good place
129135
to find a list of potential reviewers.
130-
131-
You can convert a Draft pull request to a regular pull request at any point.
136+
137+
You can convert a Draft pull request to a regular pull request at any point.
132138

133139
5. All pull requests (including drafts) trigger our CI system, which builds and
134-
tests your branch. These builds verify that code compiles and all unit tests
135-
succeed. CI build status is displayed on the GitHub pull request page, and
136-
changes will only be merged after all builds have succeeded.
140+
tests your branch. These builds verify that code compiles and all unit tests
141+
succeed. CI build status is displayed on the GitHub pull request page, and
142+
changes will only be merged after all builds have succeeded.
143+
144+
6. A status check will also ensure you've signed the requisite
145+
[Contributor License Agreement](#contributor-license-agreement-cla-and-intellectual-property).
146+
147+
7. Pull requests will be reviewed by project Committers and Contributors,
148+
who may discuss, offer constructive feedback, request changes, or approve
149+
the work.
137150

138-
6. Pull requests will be reviewed by project Committers and Contributors,
139-
who may discuss, offer constructive feedback, request changes, or approve
140-
the work.
151+
Reviewers will be added to your pull request automatically but feel free to
152+
add anyone you'd like! We'll always be happy to receive additional feedback,
153+
including from people who aren't normally involved with the project.
141154

142-
7. Upon receiving the required number of Committer approvals (as outlined
143-
in [Required Approvals](#required-approvals)), a Committer other than the PR
144-
contributor may squash and merge changes into the master branch.
155+
8. Upon receiving the required number of Committer approvals (as outlined
156+
in [Required Approvals](#required-approvals)), any Committer may squash and
157+
merge changes into the master branch.
158+
159+
## Contributor License Agreement (CLA) and Intellectual Property
160+
161+
To protect the project -- and the contributors! -- we do require a
162+
Contributor License Agreement (CLA) for anybody submitting changes.
163+
164+
* If you are an individual writing the code on your own time and you're SURE
165+
you are the sole owner of any intellectual property you contribute, you'll
166+
want to sign the Individual CLA.
167+
168+
* If you are writing the code as part of your job, or if there is any
169+
possibility that your employers might think they own any intellectual
170+
property you create, then you should use the Corporate CLA.
171+
172+
Our CLAs are based on those used by Apache and many other open source
173+
projects.
174+
175+
Every pull request runs a check using the Linux Foundation's CLA tool
176+
to verify that all committers have signed the CLA. If you haven't,
177+
the pull request's status check will display the next steps you should
178+
take. You'll log into the CLA tool which will walk you through the
179+
process.
180+
181+
The full text of the OpenCue CLAs is available in
182+
[the `tsc/` directory of the main repository](https://github.com/AcademySoftwareFoundation/OpenCue/tree/master/tsc).
145183

146184
## Required Approvals
147185

@@ -156,37 +194,38 @@ time the PR has been open to discussion. The following guidelines outline the
156194
project's established approval rules for merging:
157195

158196
* Core design decisions, large new features, or anything that might be perceived
159-
as changing the overall direction of the project should be discussed at length
160-
in the mail list before any PR is submitted, in order to: solicit feedback, try
161-
to get as much consensus as possible, and alert all the stakeholders to be on
162-
the lookout for the eventual PR when it appears.
197+
as changing the overall direction of the project should be discussed at length
198+
in the mail list before any PR is submitted, in order to: solicit feedback, try
199+
to get as much consensus as possible, and alert all the stakeholders to be on
200+
the lookout for the eventual PR when it appears.
163201

164202
* Small changes (bug fixes, docs, tests, cleanups) can be approved and merged by
165-
a single Committer.
203+
a single Committer.
166204

167205
* Big changes that can alter behavior, add major features, or present a high
168-
degree of risk should be signed off by TWO Committers, ideally one of whom
169-
should be the "owner" for that section of the codebase (if a specific owner
170-
has been designated). If the person submitting the PR is him/herself the "owner"
171-
of that section of the codebase, then only one additional Committer approval is
172-
sufficient. But in either case, a 48 hour minimum is helpful to give everybody a
173-
chance to see it, unless it's a critical emergency fix (which would probably put
174-
it in the previous "small fix" category, rather than a "big feature").
206+
degree of risk should be signed off by TWO Committers, ideally one of whom
207+
should be the "owner" for that section of the codebase (if a specific owner
208+
has been designated). If the person submitting the PR is him/herself the "owner"
209+
of that section of the codebase, then only one additional Committer approval is
210+
sufficient. But in either case, a 48 hour minimum is helpful to give everybody a
211+
chance to see it, unless it's a critical emergency fix (which would probably put
212+
it in the previous "small fix" category, rather than a "big feature").
175213

176214
* Escape valve: big changes can nonetheless be merged by a single Committer if
177-
the PR has been open for over two weeks without any unaddressed objections from
178-
other Committers. At some point, we have to assume that the people who know and
179-
care are monitoring the PRs and that an extended period without objections is
180-
really assent.
215+
the PR has been open for over two weeks without any unaddressed objections from
216+
other Committers. At some point, we have to assume that the people who know and
217+
care are monitoring the PRs and that an extended period without objections is
218+
really assent.
181219

182220
Approval must be from Committers who are not authors of the change. If one or
183221
more Committers oppose a proposed change, then the change cannot be accepted
184222
unless:
185223

186224
* Discussions and/or additional changes result in no Committers objecting to the
187-
change. Previously-objecting Committers do not necessarily have to sign-off on
188-
the change, but they should not be opposed to it.
225+
change. Previously-objecting Committers do not necessarily have to sign-off on
226+
the change, but they should not be opposed to it.
189227

190228
* The change is escalated to the TSC and the TSC votes to approve the change.
191-
This should only happen if disagreements between Committers cannot be resolved
192-
through discussion.
229+
This should only happen if disagreements between Committers cannot be resolved
230+
through discussion.
231+

‎scripts/build.sh

-24
Original file line numberDiff line numberDiff line change
@@ -14,29 +14,5 @@ if [[ ! -d ${BUILD_DIR} ]]; then
1414
git clone $OPENCUE_REPO ${BUILD_DIR}
1515
fi
1616

17-
if [[ -f ${BUILD_DIR}/CONTRIBUTING.md ]]; then
18-
19-
# Copy the specified file into a temporary file.
20-
# Copies from the first line until the first comment.
21-
# This script overwrites the remainder of the original contents.
22-
sed '/<!---/q' content/contributing/opencue/contributing.md \
23-
> contributing.tmp
24-
25-
cd ${BUILD_DIR}
26-
27-
# Determine when the file in the repo was last updated
28-
LAST_UPDATE=$(git log -n 1 --date=short CONTRIBUTING.md | grep "^Date:" | awk -F " " '{print $2}')
29-
30-
cd ..
31-
32-
# Update the publication date for the page
33-
sed -i '4s/20[0-9]\{2\}-[0-9]\{1,2\}-[0-9]\{1,2\}/'${LAST_UPDATE}'/' contributing.tmp
34-
35-
# Copy most of the source file into the temporary file
36-
tail -n +2 ${BUILD_DIR}/CONTRIBUTING.md >> contributing.tmp
37-
38-
mv contributing.tmp content/contributing/opencue/contributing.md
39-
fi
40-
4117
# Build the site
4218
hugo

0 commit comments

Comments
 (0)