1
2# Contribution Guide
3
4
5The CUE project welcomes all contributors, and there are many ways that you can
6contribute that don't involve writing code!
7
8This document guides you through the process of contributing to the CUE project.
9
10
11### How can I contribute to the CUE project?
12
13There are many ways that you can contribute to the CUE project
14that don't involve writing code.
15
16* Using CUE is a form of contributing! Especially when combined with raising
17 issues, providing feedback, tell us what works well and what doesn't, pointing
18out gaps etc.
19* Adding your CUE-based project to [Unity](https://cuelabs.dev/unity/)
20 helps ensure that we don't create releases that unintentionally break
21configurations, but also gives a wide variety of scenarios in which to test bug
22fixes, performance improvements and the like.
23* Asking questions via GitHub discussions/Slack. This might seem somewhat
24 counterintuitive, but asking questions helps to identify gaps in
25documentation, or poor signposting from the CUE homepage.
26* Raising issues with bug reports and feature requests helps us to raise the
27 quality of future CUE releases. In the case of bug reports not least because
28it provides us with real-world test cases.
29* Helping to manage issues and answer discussions. Sometimes referred to as
30 "issue gardening", this helps to share the load of triaging new issues and
31feature requests. Having issues presented in a familiar "shape", format and
32voice is a _massive_ time saver when it comes to one of the core contributors
33fixing a bug, or considering a new feature.
34* Code contributions, the main focus of this guide. The CUE project is a little
35 different from that used by other open source projects so we cover this
36process in more detail below.
37* Contributing thoughts and use cases to proposals. CUE can be and is
38 being used in many varied different ways. Sharing experience reports helps
39to shape proposals and designs.
40* Creating content. Whether it be writing blog posts, live streaming,
41 tweeting... creating content is a great way of growing the CUE community.
42Different people have different ways of explaining things, and very often these
43different styles appeal to different people. That said, if you think there is
44core documentation or guides missing from the https://cuelang.org website
45[please raise an issue to let us
46know](https://github.com/cue-lang/cue/issues/new/choose): there is not
47substitute for good core content, and it means others are then free to write
48about more interesting use cases and applications for CUE.
49* Holding community events. Whether they be virtual online events or
50 (COVID-allowing) in-person meetups, sharing experiences about using CUE is a
51very valuable way of learning for many.
52
53Thank you to everyone who contributes to the CUE community in whatever form!
54Whilst GitHub doesn't have a good means of tracking contributions outside of
55code contributions, your contributions are greatly valued!
56
57
58## Before contributing code
59
60As with many open source projects, CUE uses the GitHub [issue
61tracker](https://github.com/cue-lang/cue/issues) to not only track bugs, but
62also coordinate work on new features, bugs, designs and proposals. Given the
63inherently distributed nature of open-source this coordination is important
64because it very often serves as the main form of communication between
65contributors.
66
67You can also exchange ideas or feedback with other contributors via the
68`#contributing` [Slack channel](https://cuelang.slack.com/archives/CMY132JKY),
69as well as the contributor office hours calls which we hold via the
70[community calendar](https://cuelang.org/s/community-calendar) once per week.
71
72### Check the issue tracker
73
74Whether you already know what contribution to make, or you are searching for an
75idea, the [issue tracker](https://cuelang.org/issues) is always the first place
76to go. Issues are triaged to categorize them and manage the workflow.
77
78Most issues will be marked with one of the following workflow labels (links are
79to queries in the issue tracker):
80
81- [**Triage**](https://cuelang.org/issues?q=is%3Aissue+is%3Aopen+label%3ATriage):
82 Requires review by one of the core project maintainers.
83- [**NeedsInvestigation**](https://cuelang.org/issues?q=is%3Aissue+is%3Aopen+label%3ANeedsInvestigation):
84 The issue is not fully understood and requires analysis to understand the root
85cause.
86- [**NeedsDecision**](https://cuelang.org/issues?q=is%3Aissue+is%3Aopen+label%3ANeedsDecision):
87 the issue is relatively well understood, but the CUE team hasn't yet decided
88the best way to address it. It would be better to wait for a decision before
89writing code. If you are interested on working on an issue in this state, feel
90free to "ping" maintainers in the issue's comments if some time has passed
91without a decision.
92- [**NeedsFix**](https://cuelang.org/issues?q=is%3Aissue+is%3Aopen+label%3ANeedsFix):
93 the issue is fully understood and code can be written to fix it.
94- [**help
95 wanted**](https://cuelang.org/issues?q=is%3Aissue+is%3Aopen+label%3A"help+wanted"):
96project maintainers need input from someone who has experience or expertise to
97answer or progress this issue.
98- [**good first
99 issue**](https://cuelang.org/issues?q=is%3Aissue+is%3Aopen+label%3A"good+first+issue"):
100often combined with `NeedsFix`, `good first issue` indicates an issue is very
101likely a good candidate for someone
102looking to make their first code contribution.
103
104
105### Open an issue for any new problem
106
107Excluding very trivial changes, all contributions should be connected to an
108existing issue. Feel free to open one and discuss your plans. This process
109gives everyone a chance to validate the design, helps prevent duplication of
110effort, and ensures that the idea fits inside the goals for the language and
111tools. It also checks that the design is sound before code is written; the code
112review tool is not the place for high-level discussions.
113
114Sensitive security-related issues should be reported to <a
115href="mailto:security@cuelang.org">security@cuelang.org</a>.
116
117## Becoming a code contributor
118
119The code contribution process used by the CUE project is a little different from
120that used by other open source projects. We assume you have a basic
121understanding of [`git`](https://git-scm.com/) and [Go](https://golang.org)
122(1.21 or later).
123
124The first thing to decide is whether you want to contribute a code change via
125GitHub or GerritHub. Both workflows are fully supported, and whilst GerritHub is
126used by the core project maintainers as the "source of truth", the GitHub Pull
127Request workflow is 100% supported - contributors should feel entirely
128comfortable contributing this way if they prefer.
129
130Contributions via either workflow must be accompanied by a Developer Certificate
131of Origin.
132
133### Asserting a Developer Certificate of Origin
134
135Contributions to the CUE project must be accompanied by a [Developer Certificate
136of Origin](https://developercertificate.org/), the text of which is reproduced
137here for convenience:
138
139```
140Developer Certificate of Origin
141Version 1.1
142
143Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
1441 Letterman Drive
145Suite D4700
146San Francisco, CA, 94129
147
148Everyone is permitted to copy and distribute verbatim copies of this
149license document, but changing it is not allowed.
150
151
152Developer's Certificate of Origin 1.1
153
154By making a contribution to this project, I certify that:
155
156(a) The contribution was created in whole or in part by me and I
157 have the right to submit it under the open source license
158 indicated in the file; or
159
160(b) The contribution is based upon previous work that, to the best
161 of my knowledge, is covered under an appropriate open source
162 license and I have the right under that license to submit that
163 work with modifications, whether created in whole or in part
164 by me, under the same open source license (unless I am
165 permitted to submit under a different license), as indicated
166 in the file; or
167
168(c) The contribution was provided directly to me by some other
169 person who certified (a), (b) or (c) and I have not modified
170 it.
171
172(d) I understand and agree that this project and the contribution
173 are public and that a record of the contribution (including all
174 personal information I submit with it, including my sign-off) is
175 maintained indefinitely and may be redistributed consistent with
176 this project or the open source license(s) involved.
177```
178
179All commit messages must contain the `Signed-off-by` line with an email address
180that matches the commit author. This line asserts the Developer Certificate of Origin.
181
182When committing, use the `--signoff` (or `-s`) flag:
183
184```console
185$ git commit -s
186```
187
188You can also [set up a prepare-commit-msg git
189hook](#do-i-really-have-to-add-the--s-flag-to-each-commit) to not have to supply
190the `-s` flag.
191
192The explanations of the GitHub and GerritHub contribution workflows that follow
193assume all commits you create are signed-off in this way.
194
195
196## Preparing for GitHub Pull Request (PR) Contributions
197
198First-time contributors that are already familiar with the <a
199href="https://guides.github.com/introduction/flow/">GitHub flow</a> are
200encouraged to use the same process for CUE contributions. Even though CUE
201maintainers use GerritHub for code review, the GitHub PR workflow is 100%
202supported.
203
204Here is a checklist of the steps to follow when contributing via GitHub PR
205workflow:
206
207- **Step 0**: Review the guidelines on [Good Commit
208 Messages](#good-commit-messages), [The Review Process](#the-review-process)
209and [Miscellaneous Topics](#miscellaneous-topics)
210- **Step 1**: Create a GitHub account if you do not have one.
211- **Step 2**:
212 [Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) the CUE
213project, and clone your fork locally
214
215
216That's it! You are now ready to send a change via GitHub, the subject of the
217next section.
218
219
220
221## Sending a change via GitHub
222
223The GitHub documentation around [working with
224forks](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models)
225is extensive so we will not cover that ground here.
226
227Before making any changes it's a good idea to verify that you have a stable
228baseline by running the tests:
229
230```console
231$ go test ./...
232```
233
234Then make your planned changes and create a commit from the staged changes:
235
236```console
237# Edit files
238$ git add file1 file2
239$ git commit -s
240```
241
242Notice as we explained above, the `-s` flag asserts the Developer Certificate of
243Origin by adding a `Signed-off-by` line to a commit. When writing a commit
244message, remember the guidelines on [good commit
245messages](#good-commit-messages).
246
247You’ve written and tested your code, but before sending code out for review, run
248all the tests from the root of the repository to ensure the changes don’t break
249other packages or programs:
250
251```console
252$ go test ./...
253```
254
255Your change is now ready! [Submit a
256PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)
257in the usual way.
258
259Once your PR is submitted, a maintainer will trigger continuous integration (CI)
260workflows to run and [review your proposed
261change](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request).
262The results from CI and the review might indicate further changes are required,
263and this is where the CUE project differs from others:
264
265### Making changes to a PR
266
267Some projects accept and encourage multiple commits in a single PR. Either as a
268way of breaking down the change into smaller parts, or simply as a record of the
269various changes during the review process.
270
271The CUE project follows the Gerrit model of a single commit being the unit of
272change. Therefore, all PRs must only contain a single commit. But how does this
273work if you need to make changes requested during the review process? Does this
274not require you to create additional commits?
275
276The easiest way to maintain a single commit is to amend an existing commit.
277Rather misleadingly, this doesn't actually amend a commit, but instead creates a
278new commit which is the result of combining the last commit and any new changes:
279
280```console
281# PR is submitted, feedback received. Time to make some changes!
282
283$ git add file1 file2 # stage the files we have added/removed/changed
284$ git commit --amend # amend the last commit
285$ git push -f # push the amended commit to your PR
286```
287
288The `-f` flag is required to force push your branch to GitHub: this overrides a
289warning from `git` telling you that GitHub knows nothing about the relationship
290between the original commit in your PR and the amended commit.
291
292What happens if you accidentally create an additional commit and now have two
293commits on your branch? No worries, you can "squash" commits on a branch to
294create a single commit. See the GitHub documentation on [how to squash commits
295with GitHub
296Desktop](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/managing-commits/squashing-commits),
297or using the [`git` command
298interactively](https://medium.com/@slamflipstrom/a-beginners-guide-to-squashing-commits-with-git-rebase-8185cf6e62ec).
299
300### PR approved!
301
302With the review cycle complete, the CI checks green and your PR approved, it
303will be imported into GerritHub and then submitted. Your PR will close
304automatically as it is "merged" in GerritHub. Congratulations! You will have
305made your first contribution to the CUE project.
306
307
308## Preparing for GerritHub [CL](https://google.github.io/eng-practices/#terminology) Contributions
309
310CUE maintainers use GerritHub for code review. It has a powerful review
311interface with comments that are attributed to patchsets (versions of a change).
312Orienting changes around a single commit allows for "stacked" changes, and also
313encourages unrelated changes to be broken into separate CLs because the process
314of creating and linking CLs is so easy.
315
316For those more comfortable with contributing via GitHub PRs, please continue to
317do so: the CUE project supports both workflows so that people have a choice.
318
319For those who would like to contribute via GerritHub, read on!
320
321### Overview
322
323The first step in the GerritHub flow is registering as a CUE contributor and
324configuring your environment. Here is a checklist of the required steps to
325follow:
326
327- **Step 0**: Review the guidelines on [Good Commit Messages](#good-commit-messages), [The Review Process](#the-review-process) and [Miscellaneous Topics](#miscellaneous-topics)
328- **Step 1**: Decide which email address you want to use for contributions.
329- **Step 2**: Set up a [GerritHub](http://gerrithub.io/) account.
330- **Step 3**: [Install `git-codereview`](#step-3-install-the-git-codereview-command)
331- **Step 4**: Clone the CUE repository locally.
332
333
334We cover steps 1-4 in more detail below.
335
336### Step 1: Decide which email address you want to use for contributions
337
338A contribution to CUE is made through a specific e-mail address. Make sure to
339use the same account throughout the process and for all your subsequent
340contributions. You may need to decide whether to use a personal address or a
341corporate address. The choice will depend on who will own the copyright for the
342code that you will be writing and submitting. You might want to discuss this
343topic with your employer before deciding which account to use.
344
345You also need to make sure that your `git` tool is configured to create commits
346using your chosen e-mail address. You can either configure Git globally (as a
347default for all projects), or locally (for a single specific project). You can
348check the current configuration with this command:
349
350```console
351$ git config --global user.email # check current global config
352$ git config user.email # check current local config
353```
354
355To change the configured address:
356
357```console
358$ git config --global user.email name@example.com # change global config
359$ git config user.email name@example.com # change local config
360```
361
362### Step 2: Setup a GerritHub account
363
364If you have not used GerritHub before, setting up an account is a simple
365process:
366
367- Visit [GerritHub](http://gerrithub.io/).
368- Click "First Time Sign In".
369- Click the green "Sign In" button, to sign in using your GitHub
370 credentials.
371- When prompted "Which level of GitHub access do you need?", choose
372 "Default" and then click "Login."
373- Click "Authorize gerritforge-ltd" on the GitHub auth page.
374- Confirm account profile details and click "Next."
375
376If you want to use SSH for authentication *to GerritHub*, SSH keys can be
377[configured in your user
378profile](https://review.gerrithub.io/settings/#SSHKeys). If you choose to use
379SSH for authentication, you will not be able to use the `git-codereview`
380command that's suggested later in this document, as the command [doesn't
381support SSH-based git
382origins](https://github.com/golang/go/issues/9599#issuecomment-70538097).
383
384For HTTP Credentials, [generate a password via your user
385profile](https://review.gerrithub.io/settings/#HTTPCredentials). Then use an
386existing HTTP authentication mechanism like `.netrc`, macOS KeyChain, or some
387other [credential helper](https://git-scm.com/docs/gitcredentials). If you have
388any troubles with this step, please [raise an
389issue](https://cuelang.org/issues/new).
390
391
392### Step 3: Install the `git-codereview` command
393
394Changes to CUE must be reviewed before they are accepted, no matter who makes
395the change. A custom `git` command called `git-codereview` simplifies sending
396changes to Gerrit.
397
398Install the `git-codereview` command by running,
399
400```console
401$ go install golang.org/x/review/git-codereview@master
402```
403
404Make sure `git-codereview` is installed in your shell `PATH`, so that the
405`git` command can find it.
406Check that
407
408```console
409$ git codereview help
410```
411
412prints help text, not an error.
413
414On Windows, when using git-bash you must make sure that `git-codereview.exe` is
415in your `git` exec-path. Run `git --exec-path` to discover the right location
416then create a symbolic link or just copy the executable from $GOPATH/bin to this
417directory.
418
419### Step 4: Clone the CUE repository locally
420
421Visit https://review.gerrithub.io/admin/repos/cue-lang/cue, then click "SSH" or
422"HTTP" depending on which authentication mechanism you configured in step 2.
423Then copy and run the corresponding "Clone" command. Make sure not to use
424"ANONYMOUS HTTP", as that will not work with `git-codereview` command.
425
426## Sending a change via GerritHub
427
428Sending a change via GerritHub is quite different to the GitHub PR flow. At
429first the differences might be jarring, but with practice the workflow is
430incredibly intuitive and far more powerful when it comes to chains of "stacked"
431changes.
432
433### Step 1: Ensure you have a stable baseline
434
435With a working directory of your local clone of the CUE repository, run the tests:
436
437```console
438$ go test ./...
439```
440
441### Step 2: Prepare changes in a new branch
442
443Each CUE change must be made in a branch, created from the `master` branch. You
444can use the normal `git` commands to create a branch and stage changes:
445
446
447```console
448$ git checkout -b mybranch
449$ [edit files...]
450$ git add [files...]
451```
452
453To commit changes, instead of `git commit -s`, use `git codereview change -s`.
454
455
456```console
457$ git codereview change -s
458(opens $EDITOR)
459```
460
461You can edit the commit description in your favorite editor as usual. The
462`git codereview change` command will automatically add a unique Change-Id
463line near the bottom. That line is used by Gerrit to match successive uploads
464of the same change. Do not edit or delete it. A Change-Id looks like this:
465
466
467```
468Change-Id: I2fbdbffb3aab626c4b6f56348861b7909e3e8990
469```
470
471The `git-codereview` command also checks that you've run `go fmt` over the
472source code, and that the commit message follows the suggested format.
473
474
475If you need to edit the files again, you can stage the new changes and re-run
476`git codereview change -s`: each subsequent run will amend the existing commit
477while preserving the Change-Id.
478
479Make sure that you always keep a single commit in each branch. If you add more
480commits by mistake, you can use `git rebase` to [squash them
481together](https://medium.com/@slamflipstrom/a-beginners-guide-to-squashing-commits-with-git-rebase-8185cf6e62ec)
482into a single one.
483
484
485
486
487
488### Step 3: Test your changes
489
490You've written and tested your code, but before sending code out for review, run
491all the tests for the whole tree to ensure the changes don't break other
492packages or programs:
493
494
495```console
496$ go test ./...
497```
498
499
500### Step 4: Send changes for review
501
502Once the change is ready and tested over the whole tree, send it for review.
503This is done with the `mail` sub-command which, despite its name, doesn't
504directly mail anything; it just sends the change to Gerrit:
505
506
507```console
508$ git codereview mail
509```
510
511Gerrit assigns your change a number and URL, which `git codereview mail` will
512print, something like:
513
514
515```
516remote: New Changes:
517remote: https://review.gerrithub.io/99999 math: improved Sin, Cos and Tan precision for very large arguments
518```
519
520If you get an error instead, see the ["Troubleshooting mail
521errors"](#troubleshooting-gerrithub-mail-errors).
522
523
524### Step 5: Revise changes after a review
525
526CUE maintainers will review your code on Gerrit, and you will get notifications
527via e-mail. You can see the review on Gerrit and comment on them there. You
528can also reply [using
529e-mail](https://gerrit-review.googlesource.com/Documentation/intro-user.html#reply-by-email)
530if you prefer.
531
532
533If you need to revise your change after the review, edit the files in the same
534branch you previously created, add them to the Git staging area, and then amend
535the commit with `git codereview change`:
536
537
538```console
539$ git codereview change # amend current commit (without -s because we already signed-off, above)
540(open $EDITOR)
541$ git codereview mail # send new changes to Gerrit
542```
543
544If you don't need to change the commit description, just save and exit from the
545editor. Remember not to touch the special `Change-Id` line.
546
547
548Again, make sure that you always keep a single commit in each branch. If you
549add more commits by mistake, you can use `git rebase` to [squash them
550together](https://medium.com/@slamflipstrom/a-beginners-guide-to-squashing-commits-with-git-rebase-8185cf6e62ec)
551into a single one.
552
553
554### CL approved!
555
556With the review cycle complete, the CI checks green and your CL approved with
557`+2`, it will be submitted. Congratulations! You will have made your first
558contribution to the CUE project.
559
560
561## Good commit messages
562
563Commit messages in CUE follow a specific set of conventions, which we discuss in
564this section.
565
566
567Here is an example of a good one:
568
569
570```
571cue/ast/astutil: fix resolution bugs
572
573This fixes several bugs and documentation bugs in
574identifier resolution.
575
5761. Resolution in comprehensions would resolve identifiers
577to themselves.
578
5792. Label aliases now no longer bind to references outside
580the scope of the field. The compiler would catch this invalid
581bind and report an error, but it is better not to bind in the
582first place.
583
5843. Remove some more mentions of Template labels.
585
5864. Documentation for comprehensions was incorrect
587(Scope and Node were reversed).
588
5895. Aliases X in `X=[string]: foo` should only be visible
590in foo.
591
592Fixes #946
593```
594
595### First line
596
597The first line of the change description is conventionally a short one-line
598summary of the change, prefixed by the primary affected package
599(`cue/ast/astutil` in the example above).
600
601
602A rule of thumb is that it should be written so to complete the sentence "This
603change modifies CUE to \_\_\_\_." That means it does not start with a capital
604letter, is not a complete sentence, and actually summarizes the result of the
605change.
606
607
608Follow the first line by a blank line.
609
610
611### Main content
612
613The rest of the description elaborates and should provide context for the change
614and explain what it does. Write in complete sentences with correct punctuation,
615just like for your comments in CUE. Don't use HTML, Markdown, or any other
616markup language.
617
618
619
620### Referencing issues
621
622The special notation `Fixes #12345` associates the change with issue 12345 in
623the [CUE issue tracker](https://cuelang.org/issue/12345) When this change is
624eventually applied, the issue tracker will automatically mark the issue as
625fixed.
626
627
628If the change is a partial step towards the resolution of the issue, uses the
629notation `Updates #12345`. This will leave a comment in the issue linking back
630to the change in Gerrit, but it will not close the issue when the change is
631applied.
632
633
634All issues are tracked in the main repository's issue tracker.
635If you are sending a change against a subrepository, you must use the
636fully-qualified syntax supported by GitHub to make sure the change is linked to
637the issue in the main repository, not the subrepository (eg. `Fixes cue-lang/cue#999`).
638
639
640
641## The review process
642
643This section explains the review process in detail and how to approach reviews
644after a change has been sent to either GerritHub or GitHub.
645
646
647
648### Common mistakes
649
650When a change is sent to Gerrit, it is usually triaged within a few days. A
651maintainer will have a look and provide some initial review that for first-time
652contributors usually focuses on basic cosmetics and common mistakes. These
653include things like:
654
655
656- Commit message not following the suggested format.
657- The lack of a linked GitHub issue. The vast majority of changes require a
658 linked issue that describes the bug or the feature that the change fixes or
659implements, and consensus should have been reached on the tracker before
660proceeding with it. Gerrit reviews do not discuss the merit of the change, just
661its implementation. Only trivial or cosmetic changes will be accepted without
662an associated issue.
663
664### Continuous Integration (CI) checks
665
666After an initial reading of your change, maintainers will trigger CI checks,
667that run a full test suite and [Unity](https://cuelabs.dev/unity/)
668checks. Most CI tests complete in a few minutes, at which point a link will be
669posted in Gerrit where you can see the results, or if you are submitting a PR
670results are presented as checks towards the bottom of the PR.
671
672
673If any of the CI checks fail, follow the link and check the full logs. Try to
674understand what broke, update your change to fix it, and upload again.
675Maintainers will trigger a new CI run to see if the problem was fixed.
676
677
678### Reviews
679
680The CUE community values very thorough reviews. Think of each review comment
681like a ticket: you are expected to somehow "close" it by acting on it, either by
682implementing the suggestion or convincing the reviewer otherwise.
683
684
685After you update the change, go through the review comments and make sure to
686reply to every one. In GerritHub you can click the "Done" button to reply
687indicating that you've implemented the reviewer's suggestion and in GitHub you
688can mark a comment as resolved; otherwise, click on "Reply" and explain why you
689have not, or what you have done instead.
690
691
692It is perfectly normal for changes to go through several round of reviews, with
693one or more reviewers making new comments every time and then waiting for an
694updated change before reviewing again. This cycle happens even for experienced
695contributors, so don't be discouraged by it.
696
697
698### Voting conventions in GerritHub
699
700As they near a decision, reviewers will make a "vote" on your change.
701The Gerrit voting system involves an integer in the range -2 to +2:
702
703
704- **+2** The change is approved for being merged. Only CUE maintainers can cast
705 a +2 vote.
706- **+1** The change looks good, but either the reviewer is requesting minor
707 changes before approving it, or they are not a maintainer and cannot approve
708it, but would like to encourage an approval.
709- **-1** The change is not good the way it is but might be fixable. A -1 vote
710 will always have a comment explaining why the change is unacceptable.
711- **-2** The change is blocked by a maintainer and cannot be approved. Again,
712 there will be a comment explaining the decision.
713
714### Reviewed changed in GitHub
715
716When reviewing a PR, a reviewer will indicate the nature of their response:
717
718* **Comments** - general feedback without explicit approval.
719* **Approve** - feedback and approval for this PR to accepted and submitted in
720 GerritHub.
721* **Request changes** - feedback that must be addressed before this PR can
722 proceed.
723
724
725
726### Submitting an approved change
727
728After the code has been `+2`'ed in GerritHub or "Approved" in GitHub, an
729approver will apply it to the `master` branch using the Gerrit user interface.
730This is called "submitting the change".
731
732
733The two steps (approving and submitting) are separate because in some cases
734maintainers may want to approve it but not to submit it right away (for
735instance, the tree could be temporarily frozen).
736
737
738Submitting a change checks it into the repository. The change description will
739include a link to the code review, which will be updated with a link to the
740change in the repository. Since the method used to integrate the changes is
741Git's "Cherry Pick", the commit hashes in the repository will be changed by the
742submit operation.
743
744
745If your change has been approved for a few days without being submitted, feel
746free to write a comment in GerritHub or GitHub requesting submission.
747
748
749## Miscellaneous topics
750
751This section collects a number of other comments that are outside the
752issue/edit/code review/submit process itself.
753
754
755
756### Copyright headers
757
758Files in the CUE repository don't list author names, both to avoid clutter and
759to avoid having to keep the lists up to date. Instead, your name will appear in
760the [change log](https://review.gerrithub.io/plugins/gitiles/cue-lang/cue/+log)
761and in the [`CONTRIBUTORS`](../CONTRIBUTORS) file and perhaps the
762[`AUTHORS`](../AUTHORS) file. These files are automatically generated from the
763commit logs periodically. The [`AUTHORS`](../AUTHORS) file defines who
764“The CUE Authors”—the copyright holders—are.
765
766
767New files that you contribute should use the standard copyright header:
768
769
770```
771// Copyright 2018 The CUE Authors
772//
773// Licensed under the Apache License, Version 2.0 (the "License");
774// you may not use this file except in compliance with the License.
775// You may obtain a copy of the License at
776//
777// http://www.apache.org/licenses/LICENSE-2.0
778//
779// Unless required by applicable law or agreed to in writing, software
780// distributed under the License is distributed on an "AS IS" BASIS,
781// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
782// See the License for the specific language governing permissions and
783// limitations under the License.
784```
785
786(Use the current year if you're reading this in 2019 or beyond.)
787Files in the repository are copyrighted the year they are added.
788Do not update the copyright year on files that you change.
789
790### Troubleshooting GerritHub mail errors
791
792The most common way that the `git codereview mail` command fails is because
793the e-mail address in the commit does not match the one that you used during the
794registration process.
795
796If you see something like...
797
798
799```
800remote: Processing changes: refs: 1, done
801remote:
802remote: ERROR: In commit ab13517fa29487dcf8b0d48916c51639426c5ee9
803remote: ERROR: author email address XXXXXXXXXXXXXXXXXXX
804remote: ERROR: does not match your user account.
805```
806
807you need to configure Git for this repository to use the e-mail address that you
808registered with. To change the e-mail address to ensure this doesn't happen
809again, run:
810
811
812```console
813$ git config user.email email@address.com
814```
815
816Then change the commit to use this alternative e-mail address with this command:
817
818
819```console
820$ git commit --amend --author="Author Name <email@address.com>"
821```
822
823Then retry by running:
824
825
826```console
827$ git codereview mail
828```
829
830
831### Quickly testing your changes
832
833Running `go test ./...` for every single change to the code tree is burdensome.
834Even though it is strongly suggested to run it before sending a change, during
835the normal development cycle you may want to compile and test only the package
836you are developing.
837
838
839In this section, we'll call the directory into which you cloned the CUE
840repository `$CUEDIR`. As CUE uses Go modules, The `cue` tool built by `go
841install` will be installed in the `bin/go` in your home directory by default.
842
843If you're changing the CUE APIs or code, you can test the results in just
844this package directory.
845
846```console
847$ cd $CUEDIR/cue
848$ [make changes...]
849$ go test
850```
851
852You don't need to build a new cue tool to test it.
853Instead you can run the tests from the root.
854
855```console
856$ cd $CUEDIR
857$ go test ./...
858```
859
860To use the new tool you would still need to build and install it.
861
862
863### Specifying a reviewer / CCing others in GerritHub
864
865You can specify a reviewer or CC interested parties using the `-r` or `-cc`
866options. Both accept a comma-separated list of e-mail addresses:
867
868
869```console
870$ git codereview mail -r joe@cuelang.org -cc mabel@example.com,math-nuts@swtch.com
871```
872
873
874### Synchronize your client with GerritHub
875
876While you were working, others might have submitted changes to the repository.
877To update your local branch, run
878
879
880```console
881$ git codereview sync
882```
883
884(Under the covers this runs
885`git pull -r`.)
886
887
888
889### Reviewing code by others
890
891As part of the review process reviewers can propose changes directly (in the
892GitHub workflow this would be someone else attaching commits to a pull request).
893
894You can import these changes proposed by someone else into your local Git
895repository. On the Gerrit review page, click the "Download ▼" link in the upper
896right corner, copy the "Checkout" command and run it from your local Git repo.
897It will look something like this:
898
899
900```console
901$ git fetch https://review.gerrithub.io/a/cue-lang/cue refs/changes/67/519567/1 && git checkout FETCH_HEAD
902```
903
904To revert, change back to the branch you were working in.
905
906
907### Set up git aliases
908
909The `git-codereview` command can be run directly from the shell
910by typing, for instance,
911
912
913```console
914$ git codereview sync
915```
916
917but it is more convenient to set up aliases for `git-codereview`'s own
918subcommands, so that the above becomes,
919
920
921```console
922$ git sync
923```
924
925The `git-codereview` subcommands have been chosen to be distinct from Git's own,
926so it's safe to define these aliases. To install them, copy this text into your
927Git configuration file (usually `.gitconfig` in your home directory):
928
929
930```
931[alias]
932 change = codereview change
933 gofmt = codereview gofmt
934 mail = codereview mail
935 pending = codereview pending
936 submit = codereview submit
937 sync = codereview sync
938```
939
940
941### Sending multiple dependent changes
942
943Advanced users may want to stack up related commits in a single branch. Gerrit
944allows for changes to be dependent on each other, forming such a dependency
945chain. Each change will need to be approved and submitted separately but the
946dependency will be visible to reviewers.
947
948
949To send out a group of dependent changes, keep each change as a different commit
950under the same branch, and then run:
951
952
953```console
954$ git codereview mail HEAD
955```
956
957Make sure to explicitly specify `HEAD`, which is usually not required when
958sending single changes.
959
960This is covered in more detail in [the Gerrit
961documentation](https://gerrit-review.googlesource.com/Documentation/concept-changes.html).
962
963### Do I really have to add the `-s` flag to each commit?
964
965Earlier in this guide we explained the role the [Developer Certificate of
966Origin](https://developercertificate.org/) plays in contributions to the CUE
967project. we also explained how `git commit -s` can be used to sign-off each
968commit. But:
969
970* it's easy to forget the `-s` flag;
971* it's not always possible/easy to fix up other tools that wrap the `git commit`
972 step.
973
974You can automate the sign-off step using a [`git`
975hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks). Run the
976following commands in the root of a `git` repository where you want to
977automatically sign-off each commit:
978
979```
980cat <<'EOD' > .git/hooks/prepare-commit-msg
981#!/bin/sh
982
983NAME=$(git config user.name)
984EMAIL=$(git config user.email)
985
986if [ -z "$NAME" ]; then
987 echo "empty git config user.name"
988 exit 1
989fi
990
991if [ -z "$EMAIL" ]; then
992 echo "empty git config user.email"
993 exit 1
994fi
995
996git interpret-trailers --if-exists doNothing --trailer \
997 "Signed-off-by: $NAME <$EMAIL>" \
998 --in-place "$1"
999EOD
1000chmod +x .git/hooks/prepare-commit-msg
1001```
1002
1003If you already have a `prepare-commit-msg` hook, adapt it accordingly. The `-s`
1004flag will now be implied every time a commit is created.
1005
1006
1007## Code of Conduct
1008
1009Guidelines for participating in CUE community spaces and a reporting process for
1010handling issues can be found in the [Code of
1011Conduct](https://cuelang.org/docs/contribution_guidelines/conduct).
View as plain text