mirror of
https://github.com/PixarAnimationStudios/OpenSubdiv
synced 2024-11-08 13:30:04 +00:00
Added "contributing" doc + minor doc cleanup
This is a good start, but more could be done to make it even more useful for developers. * Updated nav_template to include contributing * Removed contributing from intro * Fixed RST compiler error in hedits * Renamed "OpenSubdiv" header in nav to "OpenSubdiv User Guide"
This commit is contained in:
jcowles
parent
c9ba285e19
commit
7f8fc77cfc
@ -69,6 +69,7 @@ if (DOCUTILS_FOUND AND PYTHONINTERP_FOUND)
|
||||
cmake_build.rst
|
||||
code_examples.rst
|
||||
compatibility.rst
|
||||
contributing.rst
|
||||
downloads.rst
|
||||
dxviewer.rst
|
||||
dxptexviewer.rst
|
||||
|
||||
129
documentation/contributing.rst
Normal file
129
documentation/contributing.rst
Normal file
@ -0,0 +1,129 @@
|
||||
..
|
||||
Copyright 2013 Pixar
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "Apache License")
|
||||
with the following modification; you may not use this file except in
|
||||
compliance with the Apache License and the following modification to it:
|
||||
Section 6. Trademarks. is deleted and replaced with:
|
||||
|
||||
6. Trademarks. This License does not grant permission to use the trade
|
||||
names, trademarks, service marks, or product names of the Licensor
|
||||
and its affiliates, except as required to comply with Section 4(c) of
|
||||
the License and to reproduce the content of the NOTICE file.
|
||||
|
||||
You may obtain a copy of the Apache License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the Apache License with the above modification is
|
||||
distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
|
||||
KIND, either express or implied. See the Apache License for the specific
|
||||
language governing permissions and limitations under the Apache License.
|
||||
|
||||
Contributing to OpenSubdiv
|
||||
--------------------------
|
||||
|
||||
----
|
||||
|
||||
Contributor License Agreement
|
||||
=============================
|
||||
|
||||
In order for us to accept code submissions (merge git pull-requests), contributors
|
||||
need to sign the Contributor License Agreement (CLA). There are two CLAs, one for
|
||||
individuals and one for corporations. As for the end-user license, both are based
|
||||
on Apache. They are found in the code repository (`individual form
|
||||
<https://github.com/PixarAnimationStudios/OpenSubdiv/blob/master/OpenSubdivCLA_individual.pdf>`__,
|
||||
`corporate form <https://github.com/PixarAnimationStudios/OpenSubdiv/blob/master/OpenSubdivCLA_corporate.pdf>`__).
|
||||
Please email the signed CLA to opensubdiv-cla@pixar.com.
|
||||
|
||||
Understand Git
|
||||
==============
|
||||
|
||||
First, you should familiarize yourself with the Git data model and commands.
|
||||
|
||||
For small changes you may not need to understand Git deeply, but for larger
|
||||
changes or working with the codebase over a long period of time, it becomes
|
||||
critical to understand more of what's going on under the hood.
|
||||
|
||||
There are many free resources on the internet, one which we've found useful is
|
||||
the following e-book:
|
||||
|
||||
`<https://github.com/pluralsight/git-internals-pdf/releases>`_
|
||||
|
||||
Recommended Git Workflow
|
||||
========================
|
||||
|
||||
Once you have a local development tree cloned and working, you can start making
|
||||
changes. You will need to integrate changes from the source tree as you work;
|
||||
the following outlines the workflow used by core OpenSubdiv engineers at Pixar
|
||||
and DreamWorks:
|
||||
|
||||
#. Fork the master repository into your own local copy. This can be done via the
|
||||
GitHub website using the "fork" button.
|
||||
|
||||
#. Clone your fork locally:
|
||||
|
||||
| git clone <your_fork_url> OpenSubdiv.<your_name>
|
||||
|
|
||||
| e.g.:
|
||||
| git clone https://github.com/jcowles/OpenSubdiv.git OpenSubdiv.jcowles
|
||||
|
||||
#. Setup two remotes, **origin** and **upstream**. Origin will be setup as a
|
||||
result of cloning your remote repository, but upstream must be setup manually:
|
||||
|
||||
| git remote add **upstream** https://github.com/PixarAnimationStudios/OpenSubdiv.git
|
||||
|
||||
Verify your remotes are setup correctly:
|
||||
|
||||
| git remote -v
|
||||
|
||||
Which should look something like:
|
||||
|
||||
| origin https://github.com/jcowles/OpenSubdiv.git (fetch)
|
||||
| origin https://github.com/jcowles/OpenSubdiv.git (push)
|
||||
| upstream https://github.com/PixarAnimationStudios/OpenSubdiv.git (fetch)
|
||||
| upstream https://github.com/PixarAnimationStudios/OpenSubdiv.git (push)
|
||||
|
||||
Finally, fetch the upstream content (this is required for the next step):
|
||||
|
||||
| git fetch upstream
|
||||
|
||||
#. Setup a new branch for each change. Working with branches in Git is its
|
||||
greatest pleasure, we strongly suggest setting up a new branch for each
|
||||
change which you plan to pull-request.
|
||||
|
||||
All work is done in the "dev" branch, so be sure to keep your change in sync
|
||||
with this upstream branch. To begin, start your new branch from the dev
|
||||
branch:
|
||||
|
||||
| git checkout -b dev-feature upstream/dev
|
||||
|
||||
#. As you are working on your feature, new changes will be merged into the
|
||||
upstream repository, to sync these changes down and preserve your local
|
||||
edits, you can continually rebase your local work:
|
||||
|
||||
| git pull --rebase upstream dev
|
||||
|
||||
Notice the "--rebase" option here. It updates the current branch to the
|
||||
upstream/dev branch and rebases all edits so they are at the head of your
|
||||
local feature branch.
|
||||
|
||||
Alternatively, you can rebase all your work at once when your feature is
|
||||
complete.
|
||||
|
||||
Sending a Pull Request
|
||||
======================
|
||||
|
||||
First, rebase and squash your changes appropriately to produce a clean set of
|
||||
changes at the head of your tree. We require changes to be grouped locally to
|
||||
ensure that rolling back changes can be done easily.
|
||||
|
||||
If you've followed the steps above, your pending change should already be queued
|
||||
up as required. If you have not, you may need to rebase and squash changes at
|
||||
this point.
|
||||
|
||||
Once the change is clean, push your changes to "origin" and go to the GitHub
|
||||
website to submit your pull request.
|
||||
|
||||
Be sure to submit your request against the "dev" branch.
|
||||
@ -23,7 +23,7 @@
|
||||
|
||||
|
||||
Hierarchical Edits
|
||||
-----------------
|
||||
------------------
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
|
||||
@ -150,17 +150,8 @@ your product.
|
||||
Contributing
|
||||
============
|
||||
|
||||
In order for us to accept code submissions (merge git pull-requests), contributors
|
||||
need to sign the Contributor License Agreement (CLA). There are two CLAs, one for
|
||||
individuals and one for corporations. As for the end-user license, both are based
|
||||
on Apache. They are found in the code repository (`individual form
|
||||
<https://github.com/PixarAnimationStudios/OpenSubdiv/blob/master/OpenSubdivCLA_individual.pdf>`__,
|
||||
`corporate form <https://github.com/PixarAnimationStudios/OpenSubdiv/blob/master/OpenSubdivCLA_corporate.pdf>`__).
|
||||
Please email the signed CLA to opensubdiv-cla@pixar.com.
|
||||
|
||||
|
||||
For more details about OpenSubdiv and other Pixar projects, see
|
||||
`Pixar Graphics Technologies <http://graphics.pixar.com>`__.
|
||||
For details on how to contribute to OpenSubdiv, see the page on
|
||||
`Contributing <contributing.html>`_
|
||||
|
||||
----
|
||||
|
||||
@ -174,6 +165,3 @@ Microsoft Research:
|
||||
Pixar Research:
|
||||
`Pixar R&D Portal <http://graphics.pixar.com/research/>`__
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -36,6 +36,7 @@
|
||||
<ul>
|
||||
<li><a href="license.html">License</a></li>
|
||||
<li><a href="getting_started.html">Getting Started</a></li>
|
||||
<li><a href="contributing.html">Contributing</a></li>
|
||||
<li><a href="cmake_build.html">Building OpenSubdiv</a></li>
|
||||
<li><a href="code_examples.html">Code Examples</a></li>
|
||||
<li><a href="roadmap.html">Roadmap</a></li>
|
||||
@ -60,7 +61,7 @@
|
||||
</ul>
|
||||
</li>
|
||||
<p></p>
|
||||
<li><a href="api_overview.html">OpenSubdiv</a>
|
||||
<li><a href="api_overview.html">OpenSubdiv User Guide</a>
|
||||
<ul>
|
||||
<li><a href="api_overview.html">API Overview</a>
|
||||
<li><a href="sdc_overview.html">Sdc</a></li>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user