mvdan.cc
this repo has no description
cue: add LICENSE and co
Change-Id: I9f6af3fc0b8176de01696e515033b12ef2603c05
+1463
+6
AUTHORS
+6
AUTHORS
···
1
+
# This is the list of CUE authors for copyright purposes.
2
+
#
3
+
# This does not necessarily list everyone who has contributed code, since in
4
+
# some cases, their employer may be the copyright holder. To see the full list
5
+
# of contributors, see the revision history in source control.
6
+
Google LLC
+30
CONTRIBUTING.md
+30
CONTRIBUTING.md
···
1
+
# Contributing to CUE
2
+
3
+
CUE is an open source project.
4
+
5
+
We'd love to accept your patches and contributions to this project. There are
6
+
just a few small guidelines you need to follow.
7
+
8
+
## Contributor License Agreement
9
+
10
+
Contributions to this project must be accompanied by a Contributor License
11
+
Agreement. You (or your employer) retain the copyright to your contribution;
12
+
this simply gives us permission to use and redistribute your contributions as
13
+
part of the project. Head over to <https://cla.developers.google.com/> to see
14
+
your current agreements on file or to sign a new one.
15
+
16
+
You generally only need to submit a CLA once, so if you've already submitted one
17
+
(even if it was for a different project), you probably don't need to do it
18
+
again.
19
+
20
+
## Code reviews
21
+
22
+
All submissions, including submissions by project members, require review. We
23
+
use Gerrit code reviews at https://cue-review.googlesource.com for this purpose.
24
+
Please read the [Contributing Guidelines][./doc/contribute.html]
25
+
before reading patches.
26
+
27
+
## Community Guidelines
28
+
29
+
This project follows [Google's Open Source Community
30
+
Guidelines](https://opensource.google.com/conduct/).
+202
LICENSE
+202
LICENSE
···
1
+
2
+
Apache License
3
+
Version 2.0, January 2004
4
+
http://www.apache.org/licenses/
5
+
6
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
7
+
8
+
1. Definitions.
9
+
10
+
"License" shall mean the terms and conditions for use, reproduction,
11
+
and distribution as defined by Sections 1 through 9 of this document.
12
+
13
+
"Licensor" shall mean the copyright owner or entity authorized by
14
+
the copyright owner that is granting the License.
15
+
16
+
"Legal Entity" shall mean the union of the acting entity and all
17
+
other entities that control, are controlled by, or are under common
18
+
control with that entity. For the purposes of this definition,
19
+
"control" means (i) the power, direct or indirect, to cause the
20
+
direction or management of such entity, whether by contract or
21
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
22
+
outstanding shares, or (iii) beneficial ownership of such entity.
23
+
24
+
"You" (or "Your") shall mean an individual or Legal Entity
25
+
exercising permissions granted by this License.
26
+
27
+
"Source" form shall mean the preferred form for making modifications,
28
+
including but not limited to software source code, documentation
29
+
source, and configuration files.
30
+
31
+
"Object" form shall mean any form resulting from mechanical
32
+
transformation or translation of a Source form, including but
33
+
not limited to compiled object code, generated documentation,
34
+
and conversions to other media types.
35
+
36
+
"Work" shall mean the work of authorship, whether in Source or
37
+
Object form, made available under the License, as indicated by a
38
+
copyright notice that is included in or attached to the work
39
+
(an example is provided in the Appendix below).
40
+
41
+
"Derivative Works" shall mean any work, whether in Source or Object
42
+
form, that is based on (or derived from) the Work and for which the
43
+
editorial revisions, annotations, elaborations, or other modifications
44
+
represent, as a whole, an original work of authorship. For the purposes
45
+
of this License, Derivative Works shall not include works that remain
46
+
separable from, or merely link (or bind by name) to the interfaces of,
47
+
the Work and Derivative Works thereof.
48
+
49
+
"Contribution" shall mean any work of authorship, including
50
+
the original version of the Work and any modifications or additions
51
+
to that Work or Derivative Works thereof, that is intentionally
52
+
submitted to Licensor for inclusion in the Work by the copyright owner
53
+
or by an individual or Legal Entity authorized to submit on behalf of
54
+
the copyright owner. For the purposes of this definition, "submitted"
55
+
means any form of electronic, verbal, or written communication sent
56
+
to the Licensor or its representatives, including but not limited to
57
+
communication on electronic mailing lists, source code control systems,
58
+
and issue tracking systems that are managed by, or on behalf of, the
59
+
Licensor for the purpose of discussing and improving the Work, but
60
+
excluding communication that is conspicuously marked or otherwise
61
+
designated in writing by the copyright owner as "Not a Contribution."
62
+
63
+
"Contributor" shall mean Licensor and any individual or Legal Entity
64
+
on behalf of whom a Contribution has been received by Licensor and
65
+
subsequently incorporated within the Work.
66
+
67
+
2. Grant of Copyright License. Subject to the terms and conditions of
68
+
this License, each Contributor hereby grants to You a perpetual,
69
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
70
+
copyright license to reproduce, prepare Derivative Works of,
71
+
publicly display, publicly perform, sublicense, and distribute the
72
+
Work and such Derivative Works in Source or Object form.
73
+
74
+
3. Grant of Patent License. Subject to the terms and conditions of
75
+
this License, each Contributor hereby grants to You a perpetual,
76
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
77
+
(except as stated in this section) patent license to make, have made,
78
+
use, offer to sell, sell, import, and otherwise transfer the Work,
79
+
where such license applies only to those patent claims licensable
80
+
by such Contributor that are necessarily infringed by their
81
+
Contribution(s) alone or by combination of their Contribution(s)
82
+
with the Work to which such Contribution(s) was submitted. If You
83
+
institute patent litigation against any entity (including a
84
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
85
+
or a Contribution incorporated within the Work constitutes direct
86
+
or contributory patent infringement, then any patent licenses
87
+
granted to You under this License for that Work shall terminate
88
+
as of the date such litigation is filed.
89
+
90
+
4. Redistribution. You may reproduce and distribute copies of the
91
+
Work or Derivative Works thereof in any medium, with or without
92
+
modifications, and in Source or Object form, provided that You
93
+
meet the following conditions:
94
+
95
+
(a) You must give any other recipients of the Work or
96
+
Derivative Works a copy of this License; and
97
+
98
+
(b) You must cause any modified files to carry prominent notices
99
+
stating that You changed the files; and
100
+
101
+
(c) You must retain, in the Source form of any Derivative Works
102
+
that You distribute, all copyright, patent, trademark, and
103
+
attribution notices from the Source form of the Work,
104
+
excluding those notices that do not pertain to any part of
105
+
the Derivative Works; and
106
+
107
+
(d) If the Work includes a "NOTICE" text file as part of its
108
+
distribution, then any Derivative Works that You distribute must
109
+
include a readable copy of the attribution notices contained
110
+
within such NOTICE file, excluding those notices that do not
111
+
pertain to any part of the Derivative Works, in at least one
112
+
of the following places: within a NOTICE text file distributed
113
+
as part of the Derivative Works; within the Source form or
114
+
documentation, if provided along with the Derivative Works; or,
115
+
within a display generated by the Derivative Works, if and
116
+
wherever such third-party notices normally appear. The contents
117
+
of the NOTICE file are for informational purposes only and
118
+
do not modify the License. You may add Your own attribution
119
+
notices within Derivative Works that You distribute, alongside
120
+
or as an addendum to the NOTICE text from the Work, provided
121
+
that such additional attribution notices cannot be construed
122
+
as modifying the License.
123
+
124
+
You may add Your own copyright statement to Your modifications and
125
+
may provide additional or different license terms and conditions
126
+
for use, reproduction, or distribution of Your modifications, or
127
+
for any such Derivative Works as a whole, provided Your use,
128
+
reproduction, and distribution of the Work otherwise complies with
129
+
the conditions stated in this License.
130
+
131
+
5. Submission of Contributions. Unless You explicitly state otherwise,
132
+
any Contribution intentionally submitted for inclusion in the Work
133
+
by You to the Licensor shall be under the terms and conditions of
134
+
this License, without any additional terms or conditions.
135
+
Notwithstanding the above, nothing herein shall supersede or modify
136
+
the terms of any separate license agreement you may have executed
137
+
with Licensor regarding such Contributions.
138
+
139
+
6. Trademarks. This License does not grant permission to use the trade
140
+
names, trademarks, service marks, or product names of the Licensor,
141
+
except as required for reasonable and customary use in describing the
142
+
origin of the Work and reproducing the content of the NOTICE file.
143
+
144
+
7. Disclaimer of Warranty. Unless required by applicable law or
145
+
agreed to in writing, Licensor provides the Work (and each
146
+
Contributor provides its Contributions) on an "AS IS" BASIS,
147
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148
+
implied, including, without limitation, any warranties or conditions
149
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150
+
PARTICULAR PURPOSE. You are solely responsible for determining the
151
+
appropriateness of using or redistributing the Work and assume any
152
+
risks associated with Your exercise of permissions under this License.
153
+
154
+
8. Limitation of Liability. In no event and under no legal theory,
155
+
whether in tort (including negligence), contract, or otherwise,
156
+
unless required by applicable law (such as deliberate and grossly
157
+
negligent acts) or agreed to in writing, shall any Contributor be
158
+
liable to You for damages, including any direct, indirect, special,
159
+
incidental, or consequential damages of any character arising as a
160
+
result of this License or out of the use or inability to use the
161
+
Work (including but not limited to damages for loss of goodwill,
162
+
work stoppage, computer failure or malfunction, or any and all
163
+
other commercial damages or losses), even if such Contributor
164
+
has been advised of the possibility of such damages.
165
+
166
+
9. Accepting Warranty or Additional Liability. While redistributing
167
+
the Work or Derivative Works thereof, You may choose to offer,
168
+
and charge a fee for, acceptance of support, warranty, indemnity,
169
+
or other liability obligations and/or rights consistent with this
170
+
License. However, in accepting such obligations, You may act only
171
+
on Your own behalf and on Your sole responsibility, not on behalf
172
+
of any other Contributor, and only if You agree to indemnify,
173
+
defend, and hold each Contributor harmless for any liability
174
+
incurred by, or claims asserted against, such Contributor by reason
175
+
of your accepting any such warranty or additional liability.
176
+
177
+
END OF TERMS AND CONDITIONS
178
+
179
+
APPENDIX: How to apply the Apache License to your work.
180
+
181
+
To apply the Apache License to your work, attach the following
182
+
boilerplate notice, with the fields enclosed by brackets "[]"
183
+
replaced with your own identifying information. (Don't include
184
+
the brackets!) The text should be enclosed in the appropriate
185
+
comment syntax for the file format. We also recommend that a
186
+
file or class name and description of purpose be included on the
187
+
same "printed page" as the copyright notice for easier
188
+
identification within third-party archives.
189
+
190
+
Copyright [yyyy] [name of copyright owner]
191
+
192
+
Licensed under the Apache License, Version 2.0 (the "License");
193
+
you may not use this file except in compliance with the License.
194
+
You may obtain a copy of the License at
195
+
196
+
http://www.apache.org/licenses/LICENSE-2.0
197
+
198
+
Unless required by applicable law or agreed to in writing, software
199
+
distributed under the License is distributed on an "AS IS" BASIS,
200
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201
+
See the License for the specific language governing permissions and
202
+
limitations under the License.
+72
README.md
+72
README.md
···
1
+
# The CUE Configuration Language
2
+
3
+
_Configure, Unify, Execute_
4
+
5
+
CUE is an open source configuration language which aims
6
+
to make complex configurations more manageable and usable.
7
+
8
+
CUE is a constrained-based language.
9
+
Constraints provide a powerful yet simple alternative
10
+
to inheritance, a common source of complexity
11
+
with other languages.
12
+
The CUE tooling also provides powerful integrated scripting
13
+
aimed at improving the overall experience of putting
14
+
configurations to good use.
15
+
16
+
Features highlights:
17
+
18
+
- JSON superset: get started quickly
19
+
- convert existing YAML and JSON
20
+
- reformatter
21
+
- automatically simplify configurations
22
+
- powerful scripting
23
+
- rich APIs designed for automated tooling
24
+
- a formalism conducive to automated reasoning
25
+
- generate CUE templates from source code
26
+
27
+
28
+
### Download and Install
29
+
30
+
#### Install From Source
31
+
32
+
If you already have Go installed, the short version is:
33
+
34
+
```
35
+
go get -u cuelang.org/go/cmd/cue
36
+
```
37
+
38
+
This will install the `cue` command line tool.
39
+
40
+
For more details see [Installing CUE][./doc/install.md].
41
+
42
+
43
+
### Learning CUE
44
+
45
+
A demonstration of how to convert and restructure and existing
46
+
set of Kubernetes configurations is available in
47
+
[written form][./doc/demo/kubernetes/Readme.md] or as
48
+
[video]().
49
+
50
+
### References
51
+
52
+
- [Language Specification][./doc/ref/spec.md]: official CUE Language specification.
53
+
54
+
- [API](https://godoc.org/cuelang.org/go/cue): the API on godoc.org
55
+
56
+
- [Builtin packages](https://godoc.org/cuelang.org/go/pkg): builtins available from CUE programs
57
+
58
+
- [`cue` Command line reference][./doc/cmd/cue.md]: the `cue` command
59
+
60
+
61
+
### Contributing
62
+
63
+
Our canonical Git repository is located at https://cue.googlesource.com.
64
+
65
+
To contribute, please read the [Contribution Guidelines][./CONTRIBUTING.md]
66
+
67
+
##### Note that we do not accept pull requests and that we use the issue tracker for bug reports and proposals only.
68
+
69
+
Unless otherwise noted, the CUE source files are distributed
70
+
under the Apache 2.0 license found in the LICENSE file.
71
+
72
+
+1153
doc/contribute.md
+1153
doc/contribute.md
···
1
+
# Contribution Guide
2
+
3
+
<p>
4
+
The CUE project welcomes all contributors.
5
+
</p>
6
+
7
+
<p>
8
+
This document is a guide to help you through the process
9
+
of contributing to the CUE project, which is a little different
10
+
from that used by other open source projects.
11
+
We assume you have a basic understanding of Git and Go.
12
+
</p>
13
+
14
+
<h2 id="contributor">Becoming a contributor</h2>
15
+
16
+
<h3>Overview</h3>
17
+
18
+
<p>
19
+
The first step is registering as a CUE contributor and configuring your environment.
20
+
Here is a checklist of the required steps to follow:
21
+
</p>
22
+
23
+
<ul>
24
+
<li>
25
+
<b>Step 0</b>: Decide on a single Google Account you will be using to contribute to CUE.
26
+
Use that account for all the following steps and make sure that <code>git</code>
27
+
is configured to create commits with that account's e-mail address.
28
+
</li>
29
+
<li>
30
+
<b>Step 1</b>: <a href="https://cla.developers.google.com/clas">Sign and submit</a> a
31
+
CLA (Contributor License Agreement).
32
+
</li>
33
+
<li>
34
+
<b>Step 2</b>: Configure authentication credentials for the CUE Git repository.
35
+
Visit <a href="https://cue.googlesource.com/">cue.googlesource.com</a>, click
36
+
on "Generate Password" (top right), and follow the instructions.
37
+
</li>
38
+
<li>
39
+
<b>Step 3</b>: Register for Gerrit, the code review tool used by the CUE team,
40
+
by <a href="https://cue-review.googlesource.com/login/">visiting this page</a>.
41
+
The CLA and the registration need to be done only once for your account.
42
+
</li>
43
+
<li>
44
+
<b>Step 4</b>: Install <code>git-codereview</code> by running
45
+
<code>go get -u golang.org/x/review/git-codereview</code>
46
+
</li>
47
+
</ul>
48
+
49
+
<!-- TODO
50
+
<p>
51
+
If you prefer, there is an automated tool that walks through these steps.
52
+
Just run:
53
+
</p>
54
+
55
+
<pre>
56
+
$ go get -u cuelang.org/x/tools/cmd/cue-contrib-init
57
+
$ cd /code/to/edit
58
+
$ cue-contrib-init
59
+
</pre>
60
+
--->
61
+
62
+
<p>
63
+
The rest of this chapter elaborates on these instructions.
64
+
If you have completed the steps above (either manually or through the tool), jump to
65
+
<a href="#before_contributing">Before contributing code</a>.
66
+
</p>
67
+
68
+
<h3 id="google_account">Step 0: Select a Google Account</h3>
69
+
70
+
<p>
71
+
A contribution to CUE is made through a Google account with a specific
72
+
e-mail address.
73
+
Make sure to use the same account throughout the process and
74
+
for all your subsequent contributions.
75
+
You may need to decide whether to use a personal address or a corporate address.
76
+
The choice will depend on who
77
+
will own the copyright for the code that you will be writing
78
+
and submitting.
79
+
You might want to discuss this topic with your employer before deciding which
80
+
account to use.
81
+
</p>
82
+
83
+
<p>
84
+
Google accounts can either be Gmail e-mail accounts, G Suite organization accounts, or
85
+
accounts associated with an external e-mail address.
86
+
For instance, if you need to use
87
+
an existing corporate e-mail that is not managed through G Suite, you can create
88
+
an account associated
89
+
<a href="https://accounts.google.com/SignUpWithoutGmail">with your existing
90
+
e-mail address</a>.
91
+
</p>
92
+
93
+
<p>
94
+
You also need to make sure that your Git tool is configured to create commits
95
+
using your chosen e-mail address.
96
+
You can either configure Git globally
97
+
(as a default for all projects), or locally (for a single specific project).
98
+
You can check the current configuration with this command:
99
+
</p>
100
+
101
+
<pre>
102
+
$ git config --global user.email # check current global config
103
+
$ git config user.email # check current local config
104
+
</pre>
105
+
106
+
<p>
107
+
To change the configured address:
108
+
</p>
109
+
110
+
<pre>
111
+
$ git config --global user.email name@example.com # change global config
112
+
$ git config user.email name@example.com # change local config
113
+
</pre>
114
+
115
+
116
+
<h3 id="cla">Step 1: Contributor License Agreement</h3>
117
+
118
+
<p>
119
+
Before sending your first change to the CUE project
120
+
you must have completed one of the following two CLAs.
121
+
Which CLA you should sign depends on who owns the copyright to your work.
122
+
</p>
123
+
124
+
<ul>
125
+
<li>
126
+
If you are the copyright holder, you will need to agree to the
127
+
<a href="https://developers.google.com/open-source/cla/individual">individual
128
+
contributor license agreement</a>, which can be completed online.
129
+
</li>
130
+
<li>
131
+
If your organization is the copyright holder, the organization
132
+
will need to agree to the
133
+
<a href="https://developers.google.com/open-source/cla/corporate">corporate
134
+
contributor license agreement</a>.<br>
135
+
</li>
136
+
</ul>
137
+
138
+
<p>
139
+
You can check your currently signed agreements and sign new ones at
140
+
the <a href="https://cla.developers.google.com/clas?pli=1&authuser=1">Google Developers
141
+
Contributor License Agreements</a> website.
142
+
If the copyright holder for your contribution has already completed the
143
+
agreement in connection with another Google open source project,
144
+
it does not need to be completed again.
145
+
</p>
146
+
147
+
<p>
148
+
If the copyright holder for the code you are submitting changes—for example,
149
+
if you start contributing code on behalf of a new company—please send mail
150
+
to the <a href="mailto:cue-dev@googlegroups.com"><code>cue-dev</code>
151
+
mailing list</a>.
152
+
This will let us know the situation so we can make sure an appropriate agreement is
153
+
completed and update the <code>AUTHORS</code> file.
154
+
</p>
155
+
156
+
157
+
<h3 id="config_git_auth">Step 2: Configure git authentication</h3>
158
+
159
+
<p>
160
+
The main CUE repository is located at
161
+
<a href="https://cue.googlesource.com">cue.googlesource.com</a>,
162
+
a Git server hosted by Google.
163
+
Authentication on the web server is made through your Google account, but
164
+
you also need to configure <code>git</code> on your computer to access it.
165
+
Follow this steps:
166
+
</p>
167
+
168
+
<ol>
169
+
<li>
170
+
Visit <a href="https://cue.googlesource.com">cue.googlesource.com</a>
171
+
and click on "Generate Password" in the page's top right menu bar.
172
+
You will be redirected to accounts.google.com to sign in.
173
+
</li>
174
+
<li>
175
+
After signing in, you will be taken to a page with the title "Configure Git".
176
+
This page contains a personalized script that when run locally will configure Git
177
+
to hold your unique authentication key.
178
+
This key is paired with one that is generated and stored on the server,
179
+
analogous to how SSH keys work.
180
+
</li>
181
+
<li>
182
+
Copy and run this script locally in your terminal to store your secret
183
+
authentication token in a <code>.gitcookies</code> file.
184
+
If you are using a Windows computer and running <code>cmd</code>,
185
+
you should instead follow the instructions in the yellow box to run the command;
186
+
otherwise run the regular script.
187
+
</li>
188
+
</ol>
189
+
190
+
<h3 id="auth">Step 3: Create a Gerrit account </h3>
191
+
192
+
<p>
193
+
Gerrit is an open-source tool used by CUE maintainers to discuss and review
194
+
code submissions.
195
+
</p>
196
+
197
+
<p>
198
+
To register your account, visit <a href="https://cue-review.googlesource.com/login/">
199
+
cue-review.googlesource.com/login/</a> and sign in once using the same Google Account you used above.
200
+
</p>
201
+
202
+
<h3 id="git-codereview_install">Step 4: Install the git-codereview command</h3>
203
+
204
+
<p>
205
+
Changes to CUE must be reviewed before they are accepted, no matter who makes the change.
206
+
A custom <code>git</code> command called <code>git-codereview</code>
207
+
simplifies sending changes to Gerrit.
208
+
</p>
209
+
210
+
<p>
211
+
Install the <code>git-codereview</code> command by running,
212
+
</p>
213
+
214
+
<pre>
215
+
$ go get -u golang.org/x/review/git-codereview
216
+
</pre>
217
+
218
+
<p>
219
+
Make sure <code>git-codereview</code> is installed in your shell path, so that the
220
+
<code>git</code> command can find it.
221
+
Check that
222
+
</p>
223
+
224
+
<pre>
225
+
$ git codereview help
226
+
</pre>
227
+
228
+
<p>
229
+
prints help text, not an error.
230
+
</p>
231
+
232
+
<p>
233
+
On Windows, when using git-bash you must make sure that
234
+
<code>git-codereview.exe</code> is in your <code>git</code> exec-path.
235
+
Run <code>git --exec-path</code> to discover the right location then create a
236
+
symbolic link or just copy the executable from $GOPATH/bin to this directory.
237
+
</p>
238
+
239
+
240
+
<h2 id="before_contributing">Before contributing code</h2>
241
+
242
+
<!--
243
+
TODO
244
+
<p>
245
+
The project welcomes code patches, but to make sure things are well
246
+
coordinated you should discuss any significant change before starting
247
+
the work.
248
+
It's recommended that you signal your intention to contribute in the
249
+
issue tracker, either by <a href="https://cuelang.org/issue/new">filing
250
+
a new issue</a> or by claiming
251
+
an <a href="https://cuelang.org/issues">existing one</a>.
252
+
</p>
253
+
-->
254
+
255
+
<h3>Check the issue tracker</h3>
256
+
257
+
<p>
258
+
Whether you already know what contribution to make, or you are searching for
259
+
an idea, the <a href="https://github.com/cuelang/core/issues">issue tracker</a> is
260
+
always the first place to go.
261
+
Issues are triaged to categorize them and manage the workflow.
262
+
</p>
263
+
264
+
<p>
265
+
Most issues will be marked with one of the following workflow labels:
266
+
</p>
267
+
268
+
<ul>
269
+
<li>
270
+
<b>NeedsInvestigation</b>: The issue is not fully understood
271
+
and requires analysis to understand the root cause.
272
+
</li>
273
+
<li>
274
+
<b>NeedsDecision</b>: the issue is relatively well understood, but the
275
+
CUE team hasn't yet decided the best way to address it.
276
+
It would be better to wait for a decision before writing code.
277
+
If you are interested on working on an issue in this state,
278
+
feel free to "ping" maintainers in the issue's comments
279
+
if some time has passed without a decision.
280
+
</li>
281
+
<li>
282
+
<b>NeedsFix</b>: the issue is fully understood and code can be written
283
+
to fix it.
284
+
</li>
285
+
</ul>
286
+
287
+
<p>
288
+
You can use GitHub's search functionality to find issues to help out with. Examples:
289
+
</p>
290
+
291
+
<ul>
292
+
<li>
293
+
Issues that need investigation: <a href="https://github.com/cuelang/core/issues?q=is%3Aissue+is%3Aopen+label%3ANeedsInvestigation"><code>is:issue is:open label:NeedsInvestigation</code></a>
294
+
</li>
295
+
<li>
296
+
Issues that need a fix: <a href="https://github.com/cuelang/core/issues?q=is%3Aissue+is%3Aopen+label%3ANeedsFix"><code>is:issue is:open label:NeedsFix</code></a>
297
+
</li>
298
+
<li>
299
+
Issues that need a fix and have a CL: <a href="https://github.com/cuelang/core/issues?q=is%3Aissue+is%3Aopen+label%3ANeedsFix+%22golang.org%2Fcl%22"><code>is:issue is:open label:NeedsFix "cuelang.org/cl"</code></a>
300
+
</li>
301
+
<li>
302
+
Issues that need a fix and do not have a CL: <a href="https://github.com/cuelang/core/issues?q=is%3Aissue+is%3Aopen+label%3ANeedsFix+NOT+%22golang.org%2Fcl%22"><code>is:issue is:open label:NeedsFix NOT "cuelang.org/cl"</code></a>
303
+
</li>
304
+
</ul>
305
+
306
+
<h3 id="design">Open an issue for any new problem</h3>
307
+
308
+
<p>
309
+
Excluding very trivial changes, all contributions should be connected
310
+
to an existing issue.
311
+
Feel free to open one and discuss your plans.
312
+
This process gives everyone a chance to validate the design,
313
+
helps prevent duplication of effort,
314
+
and ensures that the idea fits inside the goals for the language and tools.
315
+
It also checks that the design is sound before code is written;
316
+
the code review tool is not the place for high-level discussions.
317
+
</p>
318
+
319
+
<!--
320
+
TODO
321
+
<p>
322
+
When planning work, please note that the CUE project follows a <a
323
+
href="https://cuelang.org/wiki/CUE-Release-Cycle">six-month development cycle</a>.
324
+
The latter half of each cycle is a three-month feature freeze during
325
+
which only bug fixes and documentation updates are accepted.
326
+
New contributions can be sent during a feature freeze, but they will
327
+
not be merged until the freeze is over.
328
+
</p>
329
+
330
+
<p>
331
+
Significant changes to the language, libraries, or tools must go
332
+
through the
333
+
<a href="https://cuelang.org/s/proposal-process">change proposal process</a>
334
+
before they can be accepted.
335
+
</p>
336
+
337
+
<p>
338
+
Sensitive security-related issues (only!) should be reported to <a href="mailto:security@cuelang.org">security@cuelang.org</a>.
339
+
</p>
340
+
341
+
<h2 id="sending_a_change_github">Sending a change via GitHub</h2>
342
+
343
+
<p>
344
+
First-time contributors that are already familiar with the
345
+
<a href="https://guides.github.com/introduction/flow/">GitHub flow</a>
346
+
are encouraged to use the same process for CUE contributions.
347
+
Even though CUE
348
+
maintainers use Gerrit for code review, a bot called Gopherbot has been created to sync
349
+
GitHub pull requests to Gerrit.
350
+
</p>
351
+
352
+
<p>
353
+
Open a pull request as you normally would.
354
+
Gopherbot will create a corresponding Gerrit change and post a link to
355
+
it on your GitHub pull request; updates to the pull request will also
356
+
get reflected in the Gerrit change.
357
+
When somebody comments on the change, their comment will be also
358
+
posted in your pull request, so you will get a notification.
359
+
</p>
360
+
361
+
<p>
362
+
Some things to keep in mind:
363
+
</p>
364
+
365
+
<ul>
366
+
<li>
367
+
To update the pull request with new code, just push it to the branch; you can either
368
+
add more commits, or rebase and force-push (both styles are accepted).
369
+
</li>
370
+
<li>
371
+
If the request is accepted, all commits will be squashed, and the final
372
+
commit description will be composed by concatenating the pull request's
373
+
title and description.
374
+
The individual commits' descriptions will be discarded.
375
+
See <a href="#commit_messages">Writing good commit messages</a> for some
376
+
suggestions.
377
+
</li>
378
+
<li>
379
+
Gopherbot is unable to sync line-by-line codereview into GitHub: only the
380
+
contents of the overall comment on the request will be synced.
381
+
Remember you can always visit Gerrit to see the fine-grained review.
382
+
</li>
383
+
</ul>
384
+
-->
385
+
386
+
<h2 id="sending_a_change_gerrit">Sending a change via Gerrit</h2>
387
+
388
+
<p>
389
+
It is not possible to fully sync Gerrit and GitHub, at least at the moment,
390
+
so we recommend learning Gerrit.
391
+
It's different but powerful and familiarity
392
+
with help you understand the flow.
393
+
</p>
394
+
395
+
<h3>Overview</h3>
396
+
397
+
<p>
398
+
This is an overview of the overall process:
399
+
</p>
400
+
401
+
<ul>
402
+
<li>
403
+
<b>Step 1:</b> Clone the CUE source code from cue.googlesource.com
404
+
and make sure it's stable by compiling and testing it once:
405
+
<pre>
406
+
$ git clone https://cue.googlesource.com/core
407
+
$ cd core
408
+
$ go test ./...
409
+
$ go install ./cmd/cue
410
+
</pre>
411
+
</li>
412
+
413
+
<li>
414
+
<b>Step 2:</b> Prepare changes in a new branch, created from the master branch.
415
+
To commit the changes, use <code>git</code> <code>codereview</code> <code>change</code>; that
416
+
will create or amend a single commit in the branch.
417
+
<pre>
418
+
$ git checkout -b mybranch
419
+
$ [edit files...]
420
+
$ git add [files...]
421
+
$ git codereview change # create commit in the branch
422
+
$ [edit again...]
423
+
$ git add [files...]
424
+
$ git codereview change # amend the existing commit with new changes
425
+
$ [etc.]
426
+
</pre>
427
+
</li>
428
+
429
+
<li>
430
+
<b>Step 3:</b> Test your changes, re-running <code>go test</code>.
431
+
<pre>
432
+
$ go test ./... # recompile and test
433
+
</pre>
434
+
</li>
435
+
436
+
<li>
437
+
<b>Step 4:</b> Send the changes for review to Gerrit using <code>git</code>
438
+
<code>codereview</code> <code>mail</code> (which doesn't use e-mail, despite the name).
439
+
<pre>
440
+
$ git codereview mail # send changes to Gerrit
441
+
</pre>
442
+
</li>
443
+
444
+
<li>
445
+
<b>Step 5:</b> After a review, apply changes to the same single commit
446
+
and mail them to Gerrit again:
447
+
<pre>
448
+
$ [edit files...]
449
+
$ git add [files...]
450
+
$ git codereview change # update same commit
451
+
$ git codereview mail # send to Gerrit again
452
+
</pre>
453
+
</li>
454
+
</ul>
455
+
456
+
<p>
457
+
The rest of this section describes these steps in more detail.
458
+
</p>
459
+
460
+
461
+
<h3 id="checkout_go">Step 1: Clone the CUE source code</h3>
462
+
463
+
<p>
464
+
In addition to a recent CUE installation, you need to have a local copy of the source
465
+
checked out from the correct repository.
466
+
You can check out the CUE source repo onto your local file system anywhere
467
+
you want as long as it's outside your <code>GOPATH</code>.
468
+
Either clone from
469
+
<code>cue.googlesource.com</code> or from GitHub:
470
+
</p>
471
+
472
+
<pre>
473
+
$ git clone https://github.com/cuelang/core # or https://cue.googlesource.com/core
474
+
$ cd core
475
+
$ go test ./...
476
+
# go install ./cmd/cue
477
+
</pre>
478
+
479
+
<h3 id="make_branch">Step 2: Prepare changes in a new branch</h3>
480
+
481
+
<p>
482
+
Each CUE change must be made in a separate branch, created from the master branch.
483
+
You can use
484
+
the normal <code>git</code> commands to create a branch and add changes to the
485
+
staging area:
486
+
</p>
487
+
488
+
<pre>
489
+
$ git checkout -b mybranch
490
+
$ [edit files...]
491
+
$ git add [files...]
492
+
</pre>
493
+
494
+
<p>
495
+
To commit changes, instead of <code>git commit</code>, use <code>git codereview change</code>.
496
+
</p>
497
+
498
+
<pre>
499
+
$ git codereview change
500
+
(open $EDITOR)
501
+
</pre>
502
+
503
+
<p>
504
+
You can edit the commit description in your favorite editor as usual.
505
+
The <code>git</code> <code>codereview</code> <code>change</code> command
506
+
will automatically add a unique Change-Id line near the bottom.
507
+
That line is used by Gerrit to match successive uploads of the same change.
508
+
Do not edit or delete it.
509
+
A Change-Id looks like this:
510
+
</p>
511
+
512
+
<pre>
513
+
Change-Id: I2fbdbffb3aab626c4b6f56348861b7909e3e8990
514
+
</pre>
515
+
516
+
<p>
517
+
The tool also checks that you've
518
+
run <code>go</code> <code>fmt</code> over the source code, and that
519
+
the commit message follows the <a href="#commit_messages">suggested format</a>.
520
+
</p>
521
+
522
+
<p>
523
+
If you need to edit the files again, you can stage the new changes and
524
+
re-run <code>git</code> <code>codereview</code> <code>change</code>: each subsequent
525
+
run will amend the existing commit while preserving the Change-Id.
526
+
</p>
527
+
528
+
<p>
529
+
Make sure that you always keep a single commit in each branch.
530
+
If you add more
531
+
commits by mistake, you can use <code>git</code> <code>rebase</code> to
532
+
<a href="https://stackoverflow.com/questions/31668794/squash-all-your-commits-in-one-before-a-pull-request-in-github">squash them together</a>
533
+
into a single one.
534
+
</p>
535
+
536
+
537
+
<h3 id="testing">Step 3: Test your changes</h3>
538
+
539
+
<p>
540
+
You've <a href="code.html">written and tested your code</a>, but
541
+
before sending code out for review, run <i>all the tests for the whole
542
+
tree</i> to make sure the changes don't break other packages or programs:
543
+
</p>
544
+
545
+
<pre>
546
+
$ go test ./...
547
+
</pre>
548
+
549
+
550
+
<h3 id="mail">Step 4: Send changes for review</h3>
551
+
552
+
<p>
553
+
Once the change is ready and tested over the whole tree, send it for review.
554
+
This is done with the <code>mail</code> sub-command which, despite its name, doesn't
555
+
directly mail anything; it just sends the change to Gerrit:
556
+
</p>
557
+
558
+
<pre>
559
+
$ git codereview mail
560
+
</pre>
561
+
562
+
<p>
563
+
Gerrit assigns your change a number and URL, which <code>git</code> <code>codereview</code> <code>mail</code> will print, something like:
564
+
</p>
565
+
566
+
<pre>
567
+
remote: New Changes:
568
+
remote: https://cue-review.googlesource.com/99999 math: improved Sin, Cos and Tan precision for very large arguments
569
+
</pre>
570
+
571
+
<p>
572
+
If you get an error instead, check the
573
+
<a href="#troubleshooting_mail">Troubleshooting mail errors</a> section.
574
+
</p>
575
+
576
+
<p>
577
+
If your change relates to an open GitHub issue and you have followed the <a href="#commit_messages">
578
+
suggested commit message format</a>, the issue will be updated in a few minutes by a bot,
579
+
linking your Gerrit change to it in the comments.
580
+
</p>
581
+
582
+
583
+
<h3 id="revise">Step 5: Revise changes after a review</h3>
584
+
585
+
<p>
586
+
CUE maintainers will review your code on Gerrit, and you will get notifications via e-mail.
587
+
You can see the review on Gerrit and comment on them there.
588
+
You can also reply
589
+
<a href="https://gerrit-review.googlesource.com/Documentation/intro-user.html#reply-by-email">using e-mail</a>
590
+
if you prefer.
591
+
</p>
592
+
593
+
<p>
594
+
If you need to revise your change after the review, edit the files in
595
+
the same branch you previously created, add them to the Git staging
596
+
area, and then amend the commit with
597
+
<code>git</code> <code>codereview</code> <code>change</code>:
598
+
</p>
599
+
600
+
<pre>
601
+
$ git codereview change # amend current commit
602
+
(open $EDITOR)
603
+
$ git codereview mail # send new changes to Gerrit
604
+
</pre>
605
+
606
+
<p>
607
+
If you don't need to change the commit description, just save and exit from the editor.
608
+
Remember not to touch the special Change-Id line.
609
+
</p>
610
+
611
+
<p>
612
+
Again, make sure that you always keep a single commit in each branch.
613
+
If you add more
614
+
commits by mistake, you can use <code>git rebase</code> to
615
+
<a href="https://stackoverflow.com/questions/31668794/squash-all-your-commits-in-one-before-a-pull-request-in-github">squash them together</a>
616
+
into a single one.
617
+
</p>
618
+
619
+
<h2 id="commit_messages">Good commit messages</h2>
620
+
621
+
<p>
622
+
Commit messages in CUE follow a specific set of conventions,
623
+
which we discuss in this section.
624
+
</p>
625
+
626
+
<p>
627
+
Here is an example of a good one:
628
+
</p>
629
+
630
+
<pre>
631
+
math: improve Sin, Cos and Tan precision for very large arguments
632
+
633
+
The existing implementation has poor numerical properties for
634
+
large arguments, so use the McGillicutty algorithm to improve
635
+
accuracy above 1e10.
636
+
637
+
The algorithm is described at https://wikipedia.org/wiki/McGillicutty_Algorithm
638
+
639
+
Fixes #159
640
+
</pre>
641
+
642
+
<h3>First line</h3>
643
+
644
+
<p>
645
+
The first line of the change description is conventionally a short one-line
646
+
summary of the change, prefixed by the primary affected package.
647
+
</p>
648
+
649
+
<p>
650
+
A rule of thumb is that it should be written so to complete the sentence
651
+
"This change modifies CUE to _____."
652
+
That means it does not start with a capital letter, is not a complete sentence,
653
+
and actually summarizes the result of the change.
654
+
</p>
655
+
656
+
<p>
657
+
Follow the first line by a blank line.
658
+
</p>
659
+
660
+
<h3>Main content</h3>
661
+
662
+
<p>
663
+
The rest of the description elaborates and should provide context for the
664
+
change and explain what it does.
665
+
Write in complete sentences with correct punctuation, just like
666
+
for your comments in CUE.
667
+
Don't use HTML, Markdown, or any other markup language.
668
+
</p>
669
+
670
+
671
+
<h3>Referencing issues</h3>
672
+
673
+
<p>
674
+
The special notation "Fixes #12345" associates the change with issue 12345 in the
675
+
<a href="https://cuelang.org/issue/12345">CUE issue tracker</a>.
676
+
When this change is eventually applied, the issue
677
+
tracker will automatically mark the issue as fixed.
678
+
</p>
679
+
680
+
<p>
681
+
If the change is a partial step towards the resolution of the issue,
682
+
uses the notation "Updates #12345".
683
+
This will leave a comment in the issue
684
+
linking back to the change in Gerrit, but it will not close the issue
685
+
when the change is applied.
686
+
</p>
687
+
688
+
<p>
689
+
If you are sending a change against a subrepository, you must use
690
+
the fully-qualified syntax supported by GitHub to make sure the change is
691
+
linked to the issue in the main repository, not the subrepository.
692
+
All issues are tracked in the main repository's issue tracker.
693
+
The correct form is "Fixes cuelang/core#159".
694
+
</p>
695
+
696
+
697
+
<h2 id="review">The review process</h2>
698
+
699
+
<p>
700
+
This section explains the review process in detail and how to approach
701
+
reviews after a change has been mailed.
702
+
</p>
703
+
704
+
705
+
<h3 id="mistakes">Common beginner mistakes</h3>
706
+
707
+
<p>
708
+
When a change is sent to Gerrit, it is usually triaged within a few days.
709
+
A maintainer will have a look and provide some initial review that for first-time
710
+
contributors usually focuses on basic cosmetics and common mistakes.
711
+
These include things like:
712
+
</p>
713
+
714
+
<ul>
715
+
<li>
716
+
Commit message not following the <a href="#commit_messages">suggested
717
+
format</a>.
718
+
</li>
719
+
720
+
<li>
721
+
The lack of a linked GitHub issue.
722
+
The vast majority of changes
723
+
require a linked issue that describes the bug or the feature that the change
724
+
fixes or implements, and consensus should have been reached on the tracker
725
+
before proceeding with it.
726
+
Gerrit reviews do not discuss the merit of the change,
727
+
just its implementation.
728
+
<br>
729
+
Only trivial or cosmetic changes will be accepted without an associated issue.
730
+
</li>
731
+
732
+
<li>
733
+
Change sent during the freeze phase of the development cycle, when the tree
734
+
is closed for general changes.
735
+
In this case,
736
+
a maintainer might review the code with a line such as <code>R=go1.12</code>,
737
+
which means that it will be reviewed later when the tree opens for a new
738
+
development window.
739
+
You can add <code>R=go1.XX</code> as a comment yourself
740
+
if you know that it's not the correct time frame for the change.
741
+
</li>
742
+
</ul>
743
+
744
+
<!--
745
+
TODO
746
+
<h3 id="trybots">Trybots</h3>
747
+
748
+
<p>
749
+
After an initial reading of your change, maintainers will trigger trybots,
750
+
a cluster of servers that will run the full test suite on several different
751
+
architectures.
752
+
Most trybots complete in a few minutes, at which point a link will
753
+
be posted in Gerrit where you can see the results.
754
+
</p>
755
+
756
+
<p>
757
+
If the trybot run fails, follow the link and check the full logs of the
758
+
platforms on which the tests failed.
759
+
Try to understand what broke, update your patch to fix it, and upload again.
760
+
Maintainers will trigger a new trybot run to see
761
+
if the problem was fixed.
762
+
</p>
763
+
764
+
<p>
765
+
Sometimes, the tree can be broken on some platforms for a few hours; if
766
+
the failure reported by the trybot doesn't seem related to your patch, go to the
767
+
<a href="https://build.cuelang.org">Build Dashboard</a> and check if the same
768
+
failure appears in other recent commits on the same platform.
769
+
In this case,
770
+
feel free to write a comment in Gerrit to mention that the failure is
771
+
unrelated to your change, to help maintainers understand the situation.
772
+
</p>
773
+
-->
774
+
775
+
<h3 id="reviews">Reviews</h3>
776
+
777
+
<p>
778
+
The CUE community values very thorough reviews.
779
+
Think of each review comment like a ticket: you are expected to somehow "close" it
780
+
by acting on it, either by implementing the suggestion or convincing the
781
+
reviewer otherwise.
782
+
</p>
783
+
784
+
<p>
785
+
After you update the change, go through the review comments and make sure
786
+
to reply to every one.
787
+
You can click the "Done" button to reply
788
+
indicating that you've implemented the reviewer's suggestion; otherwise,
789
+
click on "Reply" and explain why you have not, or what you have done instead.
790
+
</p>
791
+
792
+
<p>
793
+
It is perfectly normal for changes to go through several round of reviews,
794
+
with one or more reviewers making new comments every time
795
+
and then waiting for an updated change before reviewing again.
796
+
This cycle happens even for experienced contributors, so
797
+
don't be discouraged by it.
798
+
</p>
799
+
800
+
<h3 id="votes">Voting conventions</h3>
801
+
802
+
<p>
803
+
As they near a decision, reviewers will make a "vote" on your change.
804
+
The Gerrit voting system involves an integer in the range -2 to +2:
805
+
</p>
806
+
807
+
<ul>
808
+
<li>
809
+
<b>+2</b> The change is approved for being merged.
810
+
Only CUE maintainers can cast a +2 vote.
811
+
</li>
812
+
<li>
813
+
<b>+1</b> The change looks good, but either the reviewer is requesting
814
+
minor changes before approving it, or they are not a maintainer and cannot
815
+
approve it, but would like to encourage an approval.
816
+
</li>
817
+
<li>
818
+
<b>-1</b> The change is not good the way it is but might be fixable.
819
+
A -1 vote will always have a comment explaining why the change is unacceptable.
820
+
</li>
821
+
<li>
822
+
<b>-2</b> The change is blocked by a maintainer and cannot be approved.
823
+
Again, there will be a comment explaining the decision.
824
+
</li>
825
+
</ul>
826
+
827
+
<h3 id="submit">Submitting an approved change</h3>
828
+
829
+
<p>
830
+
After the code has been +2'ed, an approver will
831
+
apply it to the master branch using the Gerrit user interface.
832
+
This is called "submitting the change".
833
+
</p>
834
+
835
+
<p>
836
+
The two steps (approving and submitting) are separate because in some cases maintainers
837
+
may want to approve it but not to submit it right away (for instance,
838
+
the tree could be temporarily frozen).
839
+
</p>
840
+
841
+
<p>
842
+
Submitting a change checks it into the repository.
843
+
The change description will include a link to the code review,
844
+
which will be updated with a link to the change
845
+
in the repository.
846
+
Since the method used to integrate the changes is Git's "Cherry Pick",
847
+
the commit hashes in the repository will be changed by
848
+
the submit operation.
849
+
</p>
850
+
851
+
<p>
852
+
If your change has been approved for a few days without being
853
+
submitted, feel free to write a comment in Gerrit requesting
854
+
submission.
855
+
</p>
856
+
857
+
858
+
<!--
859
+
860
+
<h3 id="more_information">More information</h3>
861
+
862
+
TODO
863
+
<p>
864
+
In addition to the information here, the CUE community maintains a <a
865
+
href="https://cuelang.org/wiki/CodeReview">CodeReview</a> wiki page.
866
+
Feel free to contribute to this page as you learn more about the review process.
867
+
</p>
868
+
-->
869
+
870
+
871
+
<h2 id="advanced_topics">Miscellaneous topics</h2>
872
+
873
+
<p>
874
+
This section collects a number of other comments that are
875
+
outside the issue/edit/code review/submit process itself.
876
+
</p>
877
+
878
+
879
+
<h3 id="copyright">Copyright headers</h3>
880
+
881
+
<p>
882
+
Files in the CUE repository don't list author names, both to avoid clutter
883
+
and to avoid having to keep the lists up to date.
884
+
Instead, your name will appear in the
885
+
<a href="https://cue.googlesource.com/core/+log">change log</a> and in the <a
886
+
href="/CONTRIBUTORS"><code>CONTRIBUTORS</code></a> file and perhaps the <a
887
+
href="/AUTHORS"><code>AUTHORS</code></a> file.
888
+
These files are automatically generated from the commit logs periodically.
889
+
The <a href="/AUTHORS"><code>AUTHORS</code></a> file defines who “The CUE
890
+
Authors”—the copyright holders—are.
891
+
</p>
892
+
893
+
<p>
894
+
New files that you contribute should use the standard copyright header:
895
+
</p>
896
+
897
+
<pre>
898
+
// Copyright 2018 The CUE Authors
899
+
//
900
+
// Licensed under the Apache License, Version 2.0 (the "License");
901
+
// you may not use this file except in compliance with the License.
902
+
// You may obtain a copy of the License at
903
+
//
904
+
// http://www.apache.org/licenses/LICENSE-2.0
905
+
//
906
+
// Unless required by applicable law or agreed to in writing, software
907
+
// distributed under the License is distributed on an "AS IS" BASIS,
908
+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
909
+
// See the License for the specific language governing permissions and
910
+
// limitations under the License.
911
+
</pre>
912
+
913
+
<p>
914
+
(Use the current year if you're reading this in 2019 or beyond.)
915
+
Files in the repository are copyrighted the year they are added.
916
+
Do not update the copyright year on files that you change.
917
+
</p>
918
+
919
+
920
+
921
+
922
+
<h3 id="troubleshooting_mail">Troubleshooting mail errors</h3>
923
+
924
+
<p>
925
+
The most common way that the <code>git</code> <code>codereview</code> <code>mail</code>
926
+
command fails is because the e-mail address in the commit does not match the one
927
+
that you used during <a href="#google_account">the registration process</a>.
928
+
929
+
<br>
930
+
If you see something like...
931
+
</p>
932
+
933
+
<pre>
934
+
remote: Processing changes: refs: 1, done
935
+
remote:
936
+
remote: ERROR: In commit ab13517fa29487dcf8b0d48916c51639426c5ee9
937
+
remote: ERROR: author email address XXXXXXXXXXXXXXXXXXX
938
+
remote: ERROR: does not match your user account.
939
+
</pre>
940
+
941
+
<p>
942
+
you need to configure Git for this repository to use the
943
+
e-mail address that you registered with.
944
+
To change the e-mail address to ensure this doesn't happen again, run:
945
+
</p>
946
+
947
+
<pre>
948
+
$ git config user.email email@address.com
949
+
</pre>
950
+
951
+
<p>
952
+
Then change the commit to use this alternative e-mail address with this command:
953
+
</p>
954
+
955
+
<pre>
956
+
$ git commit --amend --author="Author Name <email@address.com>"
957
+
</pre>
958
+
959
+
<p>
960
+
Then retry by running:
961
+
</p>
962
+
963
+
<pre>
964
+
$ git codereview mail
965
+
</pre>
966
+
967
+
968
+
<h3 id="quick_test">Quickly testing your changes</h3>
969
+
970
+
<p>
971
+
Running <code>go test ./...</code> for every single change to the code tree
972
+
is burdensome.
973
+
Even though it is strongly suggested to run it before
974
+
sending a change, during the normal development cycle you may want
975
+
to compile and test only the package you are developing.
976
+
</p>
977
+
978
+
<li>
979
+
In this section, we'll call the directory into which you cloned the CUE repository <code>$CUEDIR</code>.
980
+
As CUE uses Go modules, The <code>cue</code> tool built by
981
+
<code>go install</code> will be installed in the <code>bin/go</code> in your
982
+
home directory by default.
983
+
</li>
984
+
985
+
<li>
986
+
If you're changing the CUE APIs or code, you can test the results in just
987
+
this package directory.
988
+
989
+
<pre>
990
+
$ cd $CUEDIR/cue
991
+
$ [make changes...]
992
+
$ go test
993
+
</pre>
994
+
995
+
You don't need to build a new cue tool to test it.
996
+
Instead you can run the tests from the root.
997
+
998
+
<pre>
999
+
$ cd $CUEDIR
1000
+
$ go test ./...
1001
+
</pre>
1002
+
1003
+
To use the new tool you would still need to build and install it.
1004
+
</li>
1005
+
1006
+
1007
+
<!--
1008
+
TODO
1009
+
<h3 id="subrepos">Contributing to subrepositories (cuelang.org/x/...)</h3>
1010
+
1011
+
<p>
1012
+
If you are contributing a change to a subrepository, obtain the
1013
+
CUE package using <code>go get</code>.
1014
+
For example, to contribute
1015
+
to <code>cuelang.org/x/editor/vscode</code>, check out the code by running:
1016
+
</p>
1017
+
1018
+
<pre>
1019
+
$ go get -d cuelang.org/editor/vscode
1020
+
</pre>
1021
+
1022
+
<p>
1023
+
Then, change your directory to the package's source directory
1024
+
(<code>$GOPATH/src/cuelang.org/x/oauth2</code>), and follow the
1025
+
normal contribution flow.
1026
+
</p>
1027
+
-->
1028
+
1029
+
<h3 id="cc">Specifying a reviewer / CCing others</h3>
1030
+
1031
+
<!--
1032
+
TODO:
1033
+
1034
+
<p>
1035
+
Unless explicitly told otherwise, such as in the discussion leading
1036
+
up to sending in the change, it's better not to specify a reviewer.
1037
+
All changes are automatically CC'ed to the
1038
+
<a href="https://groups.google.com/group/cue-codereviews">cue-codereviews@googlegroups.com</a>
1039
+
mailing list.
1040
+
If this is your first ever change, there may be a moderation
1041
+
delay before it appears on the mailing list, to prevent spam.
1042
+
</p>
1043
+
-->
1044
+
1045
+
<p>
1046
+
You can specify a reviewer or CC interested parties
1047
+
using the <code>-r</code> or <code>-cc</code> options.
1048
+
Both accept a comma-separated list of e-mail addresses:
1049
+
</p>
1050
+
1051
+
<pre>
1052
+
$ git codereview mail -r joe@cuelang.org -cc mabel@example.com,math-nuts@swtch.com
1053
+
</pre>
1054
+
1055
+
1056
+
<h3 id="sync">Synchronize your client</h3>
1057
+
1058
+
<p>
1059
+
While you were working, others might have submitted changes to the repository.
1060
+
To update your local branch, run
1061
+
</p>
1062
+
1063
+
<pre>
1064
+
$ git codereview sync
1065
+
</pre>
1066
+
1067
+
<p>
1068
+
(Under the covers this runs
1069
+
<code>git</code> <code>pull</code> <code>-r</code>.)
1070
+
</p>
1071
+
1072
+
1073
+
<h3 id="download">Reviewing code by others</h3>
1074
+
1075
+
<p>
1076
+
As part of the review process reviewers can propose changes directly (in the
1077
+
GitHub workflow this would be someone else attaching commits to a pull request).
1078
+
1079
+
You can import these changes proposed by someone else into your local Git repository.
1080
+
On the Gerrit review page, click the "Download ▼" link in the upper right
1081
+
corner, copy the "Checkout" command and run it from your local Git repo.
1082
+
It will look something like this:
1083
+
</p>
1084
+
1085
+
<pre>
1086
+
$ git fetch https://cue.googlesource.com/review refs/changes/21/13245/1 && git checkout FETCH_HEAD
1087
+
</pre>
1088
+
1089
+
<p>
1090
+
To revert, change back to the branch you were working in.
1091
+
</p>
1092
+
1093
+
1094
+
<h3 id="git-config">Set up git aliases</h3>
1095
+
1096
+
<p>
1097
+
The <code>git-codereview</code> command can be run directly from the shell
1098
+
by typing, for instance,
1099
+
</p>
1100
+
1101
+
<pre>
1102
+
$ git codereview sync
1103
+
</pre>
1104
+
1105
+
<p>
1106
+
but it is more convenient to set up aliases for <code>git-codereview</code>'s own
1107
+
subcommands, so that the above becomes,
1108
+
</p>
1109
+
1110
+
<pre>
1111
+
$ git sync
1112
+
</pre>
1113
+
1114
+
<p>
1115
+
The <code>git-codereview</code> subcommands have been chosen to be distinct from
1116
+
Git's own, so it's safe to define these aliases.
1117
+
To install them, copy this text into your
1118
+
Git configuration file (usually <code>.gitconfig</code> in your home directory):
1119
+
</p>
1120
+
1121
+
<pre>
1122
+
[alias]
1123
+
change = codereview change
1124
+
gofmt = codereview gofmt
1125
+
mail = codereview mail
1126
+
pending = codereview pending
1127
+
submit = codereview submit
1128
+
sync = codereview sync
1129
+
</pre>
1130
+
1131
+
1132
+
<h3 id="multiple_changes">Sending multiple dependent changes</h3>
1133
+
1134
+
<p>
1135
+
Advanced users may want to stack up related commits in a single branch.
1136
+
Gerrit allows for changes to be dependent on each other, forming such a dependency chain.
1137
+
Each change will need to be approved and submitted separately but the dependency
1138
+
will be visible to reviewers.
1139
+
</p>
1140
+
1141
+
<p>
1142
+
To send out a group of dependent changes, keep each change as a different commit under
1143
+
the same branch, and then run:
1144
+
</p>
1145
+
1146
+
<pre>
1147
+
$ git codereview mail HEAD
1148
+
</pre>
1149
+
1150
+
<p>
1151
+
Make sure to explicitly specify <code>HEAD</code>, which is usually not required when sending
1152
+
single changes.
1153
+
</p>