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