1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
|
..
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
--------------------------
.. contents::
:local:
:backlinks: none
----
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/release/OpenSubdivCLA_individual.pdf>`__,
`corporate form <https://github.com/PixarAnimationStudios/OpenSubdiv/blob/release/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 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/yourusername/OpenSubdiv.git OpenSubdiv.yourusername
#. 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/yourusername/OpenSubdiv.git (fetch)
| origin https://github.com/yourusername/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.
|
