Skip to content
Permalink
Browse files
Sync content from and remove references to CONTRIBUTING.md. (#194)
  • Loading branch information
bcipriano committed Aug 10, 2020
1 parent b3083ff commit 3168e35b95638f551714af7fcb22379171d35cf2
Show file tree
Hide file tree
Showing 5 changed files with 104 additions and 90 deletions.
@@ -1,4 +1,4 @@
## Contribution guidelines

So, you want to contribute to the OpenCue web site? To find out how you can help, refer to OpenCue's overall
[contribution guidelines](https://github.com/AcademySoftwareFoundation/OpenCue/blob/master/CONTRIBUTING.md).
[contribution guidelines](https://www.opencue.io/contributing/opencue/contributing/).
@@ -14,9 +14,8 @@ run, to propose changes to the OpenCue documentation.
### Before you begin

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

As with all changes to OpenCue, you also need to be familiar with common Git
workflows.
@@ -65,7 +65,7 @@ <h1>What is OpenCue?</h1>
Join the OpenCue [discussion forum](https://lists.aswf.io/g/opencue-user) for users and admins.
{{% /blocks/feature %}}

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

@@ -1,20 +1,14 @@
---
title: "Contributing to OpenCue"
linkTitle: "Contributing to OpenCue"
date: 2019-07-25
date: 2020-05-04
weight: 1
description: >
Contribute to OpenCue development
---

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

<!---The contents of page published at
https://www.opencue.io/contributing/opencue/contributing/ is single sourced
from the CONTRIBUTING.md file in the OpenCue repository. To suggest suggest
changes to this content, send a pull request for the file at
https://github.com/AcademySoftwareFoundation/OpenCue/blob/master/CONTRIBUTING.md--->

Code contributions to OpenCue are welcome! Please review this document to get
a briefing on our process.

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

## Contributor License Agreement (CLA) and Intellectual Property
## GitHub Issues

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

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

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

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

Every pull request runs a check using the Linux Foundation's CLA tool
to verify that all committers have signed the CLA. If you haven't,
the pull request's status check will display the next steps you should
take. You'll log into the CLA tool which will walk you through the
process.
- Avoids duplicating work. You may find that your planned issue is already
being worked on by someone else! If an issue has an existing assignee,
coordinate with them to find out the current state of their work and if
you can assist. If you don't get a response, or the issue seems to be stale,
reach out to a [Code Owner](./CODEOWNERS) to escalate.

- Provides a centralized place to track related work. There may be related
discussion, and many issues are complex enough to require more than one
pull request to be fully resolved. The issue page provides a home for
all of that material, which is very helpful for future contributors to
look back on.

- Helps us populate our release notes. Published
[OpenCue releases](https://github.com/AcademySoftwareFoundation/OpenCue/releases)
use Github issue or pull request numbers to identify what has changed in
each release.

Nearly all pull requests should have an issue associated with them.

## Development and Pull Requests

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

2. Make changes, compile, and test thoroughly. Code style should match existing
style and conventions, and changes should be focused on the topic the pull
request will be addressing. Make unrelated changes in a separate topic branch
with a separate pull request.
style and conventions, and changes should be focused on the topic the pull
request will be addressing. Make unrelated changes in a separate topic branch
with a separate pull request.

3. Push commits to your fork.

4. Create a Github pull request from your topic branch. This can be
a normal pull request or a **draft** pull request:
a normal pull request or a **draft** pull request:

- Normal pull request: Use this if you feel like your change is
ready to be merged or close to that. Reviews will be automatically
requested from all of our Code Owners, but feel free to add others
if you'd like -- we love to get as much feedback as we can!

- Draft pull request: Use this if you feel like your change isn't
ready to be merged -- maybe it's just an idea you have -- but
you want feedback anyway. Reviews will not be automatically
requested, but feel free to add reviewers anyway and we'll be happy
to provide feedback -- [CODEOWNERS](./CODEOWNERS) is a good place
to find a list of potential reviewers.
You can convert a Draft pull request to a regular pull request at any point.

You can convert a Draft pull request to a regular pull request at any point.

5. All pull requests (including drafts) trigger our CI system, which builds and
tests your branch. These builds verify that code compiles and all unit tests
succeed. CI build status is displayed on the GitHub pull request page, and
changes will only be merged after all builds have succeeded.
tests your branch. These builds verify that code compiles and all unit tests
succeed. CI build status is displayed on the GitHub pull request page, and
changes will only be merged after all builds have succeeded.

6. A status check will also ensure you've signed the requisite
[Contributor License Agreement](#contributor-license-agreement-cla-and-intellectual-property).

7. Pull requests will be reviewed by project Committers and Contributors,
who may discuss, offer constructive feedback, request changes, or approve
the work.

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

7. Upon receiving the required number of Committer approvals (as outlined
in [Required Approvals](#required-approvals)), a Committer other than the PR
contributor may squash and merge changes into the master branch.
8. Upon receiving the required number of Committer approvals (as outlined
in [Required Approvals](#required-approvals)), any Committer may squash and
merge changes into the master branch.

## Contributor License Agreement (CLA) and Intellectual Property

To protect the project -- and the contributors! -- we do require a
Contributor License Agreement (CLA) for anybody submitting changes.

* If you are an individual writing the code on your own time and you're SURE
you are the sole owner of any intellectual property you contribute, you'll
want to sign the Individual CLA.

* If you are writing the code as part of your job, or if there is any
possibility that your employers might think they own any intellectual
property you create, then you should use the Corporate CLA.

Our CLAs are based on those used by Apache and many other open source
projects.

Every pull request runs a check using the Linux Foundation's CLA tool
to verify that all committers have signed the CLA. If you haven't,
the pull request's status check will display the next steps you should
take. You'll log into the CLA tool which will walk you through the
process.

The full text of the OpenCue CLAs is available in
[the `tsc/` directory of the main repository](https://github.com/AcademySoftwareFoundation/OpenCue/tree/master/tsc).

## Required Approvals

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

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

* Small changes (bug fixes, docs, tests, cleanups) can be approved and merged by
a single Committer.
a single Committer.

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

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

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

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

* The change is escalated to the TSC and the TSC votes to approve the change.
This should only happen if disagreements between Committers cannot be resolved
through discussion.
This should only happen if disagreements between Committers cannot be resolved
through discussion.

@@ -14,29 +14,5 @@ if [[ ! -d ${BUILD_DIR} ]]; then
git clone $OPENCUE_REPO ${BUILD_DIR}
fi

if [[ -f ${BUILD_DIR}/CONTRIBUTING.md ]]; then

# Copy the specified file into a temporary file.
# Copies from the first line until the first comment.
# This script overwrites the remainder of the original contents.
sed '/<!---/q' content/contributing/opencue/contributing.md \
> contributing.tmp

cd ${BUILD_DIR}

# Determine when the file in the repo was last updated
LAST_UPDATE=$(git log -n 1 --date=short CONTRIBUTING.md | grep "^Date:" | awk -F " " '{print $2}')

cd ..

# Update the publication date for the page
sed -i '4s/20[0-9]\{2\}-[0-9]\{1,2\}-[0-9]\{1,2\}/'${LAST_UPDATE}'/' contributing.tmp

# Copy most of the source file into the temporary file
tail -n +2 ${BUILD_DIR}/CONTRIBUTING.md >> contributing.tmp

mv contributing.tmp content/contributing/opencue/contributing.md
fi

# Build the site
hugo

0 comments on commit 3168e35

Please sign in to comment.