github.com/solo-io/cue@v0.4.7/doc/contribute.md (about) 1 # Contribution Guide 2 3 4 The CUE project welcomes all contributors. 5 6 This document is a guide to help you through the process 7 of contributing to the CUE project, which is a little different 8 from that used by other open source projects. 9 We assume you have a basic understanding of Git and Go. 10 11 12 ## Becoming a contributor 13 14 ### Overview 15 16 The first step is registering as a CUE contributor and configuring your environment. 17 Here is a checklist of the required steps to follow: 18 19 20 - **Step 0**: Decide on a single Google Account you will be using to contribute to CUE. 21 Use that account for all the following steps and make sure that `git` 22 is configured to create commits with that account's e-mail address. 23 - **Step 1**: [Sign and submit](https://cla.developers.google.com/clas) a 24 CLA (Contributor License Agreement). 25 - **Step 2**: Configure authentication credentials for the CUE Git repository. 26 Visit 27 [cue.googlesource.com](https://cue.googlesource.com), click 28 on "Generate Password" (top right), and follow the instructions. 29 - **Step 3**: Register for Gerrit, the code review tool used by the CUE team, 30 by [visiting this page](https://cue-review.googlesource.com/login/). 31 The CLA and the registration need to be done only once for your account. 32 - **Step 4**: Install `git-codereview` by running: `GO111MODULE=on go get 33 golang.org/x/review/git-codereview` (or just `go install 34 golang.org/x/review/git-codereview@latest` if you are using Go 1.16) 35 36 <!-- Keep the above steps in sync with cmd/cue/cmd/testdata/script/contributing_install*.txt --> 37 38 39 <!-- TODO 40 If you prefer, there is an automated tool that walks through these steps. 41 Just run: 42 43 44 ``` 45 $ go get -u cuelang.org/x/tools/cmd/cue-contrib-init 46 $ cd /code/to/edit 47 $ cue-contrib-init 48 ``` 49 ---> 50 51 The rest of this chapter elaborates on these instructions. 52 If you have completed the steps above (either manually or through the tool), jump to 53 Before contributing code. 54 55 56 ### Step 0: Select a Google Account 57 58 A contribution to CUE is made through a Google account with a specific 59 e-mail address. 60 Make sure to use the same account throughout the process and 61 for all your subsequent contributions. 62 You may need to decide whether to use a personal address or a corporate address. 63 The choice will depend on who 64 will own the copyright for the code that you will be writing 65 and submitting. 66 You might want to discuss this topic with your employer before deciding which 67 account to use. 68 69 70 Google accounts can either be Gmail e-mail accounts, G Suite organization accounts, or 71 accounts associated with an external e-mail address. 72 For instance, if you need to use 73 an existing corporate e-mail that is not managed through G Suite, you can create 74 an account associated 75 [with your existing 76 e-mail address](https://accounts.google.com/SignUpWithoutGmail). 77 78 79 You also need to make sure that your Git tool is configured to create commits 80 using your chosen e-mail address. 81 You can either configure Git globally 82 (as a default for all projects), or locally (for a single specific project). 83 You can check the current configuration with this command: 84 85 86 ``` 87 $ git config --global user.email # check current global config 88 $ git config user.email # check current local config 89 ``` 90 91 To change the configured address: 92 93 94 ``` 95 $ git config --global user.email name@example.com # change global config 96 $ git config user.email name@example.com # change local config 97 ``` 98 99 100 ### Step 1: Contributor License Agreement 101 102 Before sending your first change to the CUE project 103 you must have completed one of the following two CLAs. 104 Which CLA you should sign depends on who owns the copyright to your work. 105 106 107 - If you are the copyright holder, you will need to agree to the 108 [individual contributor license agreement](https://developers.google.com/open-source/cla/individual), 109 which can be completed online. 110 - If your organization is the copyright holder, the organization 111 will need to agree to the 112 [corporate 113 contributor license agreement](https://developers.google.com/open-source/cla/corporate). 114 115 You can check your currently signed agreements and sign new ones at 116 the 117 [Google Developers Contributor License Agreements](https://cla.developers.google.com/clas?pli=1&authuser=1) website. 118 If the copyright holder for your contribution has already completed the 119 agreement in connection with another Google open source project, 120 it does not need to be completed again. 121 122 123 If the copyright holder for the code you are submitting changes—for example, 124 if you start contributing code on behalf of a new company—please send mail 125 to the [`cue-dev` mailing list](mailto:cue-dev@googlegroups.com). 126 This will let us know the situation so we can make sure an appropriate agreement is 127 completed and update the `AUTHORS` file. 128 129 130 131 ### Step 2: Configure git authentication 132 133 The remaining two steps only apply if you wish to contribute through Gerrit, 134 which is the source of truth for the CUE project. You can also send Pull 135 Requests to the mirror at https://github.com/cuelang/cue. 136 137 The main CUE repository is located at 138 [cue.googlesource.com](https://cue.googlesource.com), 139 a Git server hosted by Google. 140 Authentication on the web server is made through your Google account, but 141 you also need to configure `git` on your computer to access it. 142 Follow this steps: 143 144 145 - Visit [cue.googlesource.com](https://cue.googlesource.com) 146 and click on "Generate Password" in the page's top right menu bar. 147 You will be redirected to accounts.google.com to sign in. 148 - After signing in, you will be taken to a page with the title "Configure Git". 149 This page contains a personalized script that when run locally will configure Git 150 to hold your unique authentication key. 151 This key is paired with one that is generated and stored on the server, 152 analogous to how SSH keys work. 153 - Copy and run this script locally in your terminal to store your secret 154 authentication token in a `.gitcookies` file. 155 If you are using a Windows computer and running `cmd`, 156 you should instead follow the instructions in the yellow box to run the command; 157 otherwise run the regular script. 158 159 ### Step 3: Create a Gerrit account 160 161 Gerrit is an open-source tool used by CUE maintainers to discuss and review 162 code submissions. 163 164 165 To register your account, visit 166 [cue-review.googlesource.com/login/](https://cue-review.googlesource.com/login/) 167 and sign in once using the same Google Account you used above. 168 169 170 ### Step 4: Install the git-codereview command 171 172 Changes to CUE must be reviewed before they are accepted, no matter who makes the change. 173 A custom `git` command called `git-codereview` 174 simplifies sending changes to Gerrit. 175 176 <!-- Keep the following in sync with cmd/cue/cmd/testdata/script/contributing_install*.txt --> 177 178 Install the `git-codereview` command by running, 179 180 ``` 181 $ GO111MODULE=on go get golang.org/x/review/git-codereview 182 ``` 183 184 or with Go 1.16: 185 186 ``` 187 $ go install golang.org/x/review/git-codereview@latest 188 ``` 189 190 Make sure `git-codereview` is installed in your shell path, so that the 191 `git` command can find it. 192 Check that 193 194 195 ``` 196 $ git codereview help 197 ``` 198 199 prints help text, not an error. 200 201 202 On Windows, when using git-bash you must make sure that 203 `git-codereview.exe` is in your `git` exec-path. 204 Run `git --exec-path` to discover the right location then create a 205 symbolic link or just copy the executable from $GOPATH/bin to this directory. 206 207 208 209 ## Before contributing code 210 211 <!-- 212 TODO 213 The project welcomes code patches, but to make sure things are well 214 coordinated you should discuss any significant change before starting 215 the work. 216 It's recommended that you signal your intention to contribute in the 217 issue tracker, either by <a href="https://cuelang.org/issue/new">filing 218 a new issue</a> or by claiming 219 an <a href="https://cuelang.org/issues">existing one</a>. 220 221 --> 222 223 ### Check the issue tracker 224 225 Whether you already know what contribution to make, or you are searching for 226 an idea, the [issue tracker](https://github.com/cuelang/cue/issues) is 227 always the first place to go. 228 Issues are triaged to categorize them and manage the workflow. 229 230 231 Most issues will be marked with one of the following workflow labels: 232 233 234 - **NeedsInvestigation**: The issue is not fully understood 235 and requires analysis to understand the root cause. 236 - **NeedsDecision**: the issue is relatively well understood, but the 237 CUE team hasn't yet decided the best way to address it. 238 It would be better to wait for a decision before writing code. 239 If you are interested on working on an issue in this state, 240 feel free to "ping" maintainers in the issue's comments 241 if some time has passed without a decision. 242 - **NeedsFix**: the issue is fully understood and code can be written 243 to fix it. 244 245 You can use GitHub's search functionality to find issues to help out with. Examples: 246 247 248 - Issues that need investigation: 249 [`is:issue is:open label:NeedsInvestigation`]( 250 https://github.com/cuelang/cue/issues?q=is%3Aissue+is%3Aopen+label%3ANeedsInvestigation) 251 - Issues that need a fix: 252 [`is:issue is:open label:NeedsFix`](https://github.com/cuelang/cue/issues?q=is%3Aissue+is%3Aopen+label%3ANeedsFix) 253 - Issues that need a fix and have a CL: 254 [`is:issue is:open label:NeedsFix "cuelang.org/cl"`](https://github.com/cuelang/cue/issues?q=is%3Aissue+is%3Aopen+label%3ANeedsFix+%22golang.org%2Fcl%22) 255 - Issues that need a fix and do not have a CL: 256 [`is:issue is:open label:NeedsFix NOT "cuelang.org/cl"`](https://github.com/cuelang/cue/issues?q=is%3Aissue+is%3Aopen+label%3ANeedsFix+NOT+%22golang.org%2Fcl%22) 257 258 ### Open an issue for any new problem 259 260 Excluding very trivial changes, all contributions should be connected 261 to an existing issue. 262 Feel free to open one and discuss your plans. 263 This process gives everyone a chance to validate the design, 264 helps prevent duplication of effort, 265 and ensures that the idea fits inside the goals for the language and tools. 266 It also checks that the design is sound before code is written; 267 the code review tool is not the place for high-level discussions. 268 269 270 <!-- 271 TODO 272 When planning work, please note that the CUE project follows a <a 273 href="https://cuelang.org/wiki/CUE-Release-Cycle">six-month development cycle</a>. 274 The latter half of each cycle is a three-month feature freeze during 275 which only bug fixes and documentation updates are accepted. 276 New contributions can be sent during a feature freeze, but they will 277 not be merged until the freeze is over. 278 279 280 Significant changes to the language, libraries, or tools must go 281 through the 282 <a href="https://cuelang.org/s/proposal-process">change proposal process</a> 283 before they can be accepted. 284 285 286 Sensitive security-related issues (only!) should be reported to <a href="mailto:security@cuelang.org">security@cuelang.org</a>. 287 288 289 ## Sending a change via GitHub 290 291 First-time contributors that are already familiar with the 292 <a href="https://guides.github.com/introduction/flow/">GitHub flow</a> 293 are encouraged to use the same process for CUE contributions. 294 Even though CUE 295 maintainers use Gerrit for code review, a bot called Gopherbot has been created to sync 296 GitHub pull requests to Gerrit. 297 298 299 Open a pull request as you normally would. 300 Gopherbot will create a corresponding Gerrit change and post a link to 301 it on your GitHub pull request; updates to the pull request will also 302 get reflected in the Gerrit change. 303 When somebody comments on the change, their comment will be also 304 posted in your pull request, so you will get a notification. 305 306 307 Some things to keep in mind: 308 309 310 <ul> 311 <li> 312 To update the pull request with new code, just push it to the branch; you can either 313 add more commits, or rebase and force-push (both styles are accepted). 314 </li> 315 <li> 316 If the request is accepted, all commits will be squashed, and the final 317 commit description will be composed by concatenating the pull request's 318 title and description. 319 The individual commits' descriptions will be discarded. 320 See Writing good commit messages</a> for some 321 suggestions. 322 </li> 323 <li> 324 Gopherbot is unable to sync line-by-line codereview into GitHub: only the 325 contents of the overall comment on the request will be synced. 326 Remember you can always visit Gerrit to see the fine-grained review. 327 </li> 328 </ul> 329 --> 330 331 ## Sending a change via Gerrit 332 333 It is not possible to fully sync Gerrit and GitHub, 334 although things are improving, 335 so we recommend learning Gerrit. 336 It's different but powerful and familiarity 337 with help you understand the flow. 338 339 340 ### Overview 341 342 This is an overview of the overall process: 343 344 345 - **Step 1:** Clone the CUE source code from cue.googlesource.com 346 and make sure it's stable by compiling and testing it once: 347 ``` 348 $ git clone https://cue.googlesource.com/cue 349 $ cd cue 350 $ go test ./... 351 $ go install ./cmd/cue 352 ``` 353 354 - **Step 2:** Prepare changes in a new branch, created from the master branch. 355 To commit the changes, use `git` `codereview` `change`; that 356 will create or amend a single commit in the branch. 357 ``` 358 $ git checkout -b mybranch 359 $ [edit files...] 360 $ git add [files...] 361 $ git codereview change # create commit in the branch 362 $ [edit again...] 363 $ git add [files...] 364 $ git codereview change # amend the existing commit with new changes 365 $ [etc.] 366 ``` 367 368 - **Step 3:** Test your changes, re-running `go test`. 369 ``` 370 $ go test ./... # recompile and test 371 ``` 372 373 - **Step 4:** Send the changes for review to Gerrit using `git` 374 `codereview` `mail` (which doesn't use e-mail, despite the name). 375 ``` 376 $ git codereview mail # send changes to Gerrit 377 ``` 378 379 - **Step 5:** After a review, apply changes to the same single commit 380 and mail them to Gerrit again: 381 ``` 382 $ [edit files...] 383 $ git add [files...] 384 $ git codereview change # update same commit 385 $ git codereview mail # send to Gerrit again 386 ``` 387 388 The rest of this section describes these steps in more detail. 389 390 391 392 ### Step 1: Clone the CUE source code 393 394 In addition to a recent CUE installation, you need to have a local copy of the source 395 checked out from the correct repository. 396 You can check out the CUE source repo onto your local file system anywhere 397 you want as long as it's outside your `GOPATH`. 398 Either clone from 399 `cue.googlesource.com` or from GitHub: 400 401 402 ``` 403 $ git clone https://github.com/cuelang/cue # or https://cue.googlesource.com/cue 404 $ cd cue 405 $ go test ./... 406 # go install ./cmd/cue 407 ``` 408 409 ### Step 2: Prepare changes in a new branch 410 411 Each CUE change must be made in a separate branch, created from the master branch. 412 You can use 413 the normal `git` commands to create a branch and add changes to the 414 staging area: 415 416 417 ``` 418 $ git checkout -b mybranch 419 $ [edit files...] 420 $ git add [files...] 421 ``` 422 423 To commit changes, instead of `git commit`, use `git codereview change`. 424 425 426 ``` 427 $ git codereview change 428 (open $EDITOR) 429 ``` 430 431 You can edit the commit description in your favorite editor as usual. 432 The `git` `codereview` `change` command 433 will automatically add a unique Change-Id line near the bottom. 434 That line is used by Gerrit to match successive uploads of the same change. 435 Do not edit or delete it. 436 A Change-Id looks like this: 437 438 439 ``` 440 Change-Id: I2fbdbffb3aab626c4b6f56348861b7909e3e8990 441 ``` 442 443 The tool also checks that you've 444 run `go` `fmt` over the source code, and that 445 the commit message follows the suggested format. 446 447 448 If you need to edit the files again, you can stage the new changes and 449 re-run `git` `codereview` `change`: each subsequent 450 run will amend the existing commit while preserving the Change-Id. 451 452 453 Make sure that you always keep a single commit in each branch. 454 If you add more 455 commits by mistake, you can use `git` `rebase` to 456 [squash them together](https://stackoverflow.com/questions/31668794/squash-all-your-commits-in-one-before-a-pull-request-in-github) 457 into a single one. 458 459 460 461 ### Step 3: Test your changes 462 463 You've written and tested your code, but 464 before sending code out for review, run <i>all the tests for the whole 465 tree</i> to make sure the changes don't break other packages or programs: 466 467 468 ``` 469 $ go test ./... 470 ``` 471 472 473 ### Step 4: Send changes for review 474 475 Once the change is ready and tested over the whole tree, send it for review. 476 This is done with the `mail` sub-command which, despite its name, doesn't 477 directly mail anything; it just sends the change to Gerrit: 478 479 480 ``` 481 $ git codereview mail 482 ``` 483 484 Gerrit assigns your change a number and URL, which `git` `codereview` `mail` will print, something like: 485 486 487 ``` 488 remote: New Changes: 489 remote: https://cue-review.googlesource.com/99999 math: improved Sin, Cos and Tan precision for very large arguments 490 ``` 491 492 If you get an error instead, check the 493 Troubleshooting mail errors section. 494 495 496 If your change relates to an open GitHub issue and you have followed the 497 suggested commit message format, the issue will be updated in a few minutes by a bot, 498 linking your Gerrit change to it in the comments. 499 500 501 502 ### Step 5: Revise changes after a review 503 504 CUE maintainers will review your code on Gerrit, and you will get notifications via e-mail. 505 You can see the review on Gerrit and comment on them there. 506 You can also reply 507 [using e-mail](https://gerrit-review.googlesource.com/Documentation/intro-user.html#reply-by-email) 508 if you prefer. 509 510 511 If you need to revise your change after the review, edit the files in 512 the same branch you previously created, add them to the Git staging 513 area, and then amend the commit with 514 `git` `codereview` `change`: 515 516 517 ``` 518 $ git codereview change # amend current commit 519 (open $EDITOR) 520 $ git codereview mail # send new changes to Gerrit 521 ``` 522 523 If you don't need to change the commit description, just save and exit from the editor. 524 Remember not to touch the special Change-Id line. 525 526 527 Again, make sure that you always keep a single commit in each branch. 528 If you add more 529 commits by mistake, you can use `git rebase` to 530 [squash them together](https://stackoverflow.com/questions/31668794/squash-all-your-commits-in-one-before-a-pull-request-in-github) 531 into a single one. 532 533 534 ## Good commit messages 535 536 Commit messages in CUE follow a specific set of conventions, 537 which we discuss in this section. 538 539 540 Here is an example of a good one: 541 542 543 ``` 544 math: improve Sin, Cos and Tan precision for very large arguments 545 546 The existing implementation has poor numerical properties for 547 large arguments, so use the McGillicutty algorithm to improve 548 accuracy above 1e10. 549 550 The algorithm is described at https://wikipedia.org/wiki/McGillicutty_Algorithm 551 552 Fixes #159 553 ``` 554 555 ### First line 556 557 The first line of the change description is conventionally a short one-line 558 summary of the change, prefixed by the primary affected package. 559 560 561 A rule of thumb is that it should be written so to complete the sentence 562 "This change modifies CUE to _____." 563 That means it does not start with a capital letter, is not a complete sentence, 564 and actually summarizes the result of the change. 565 566 567 Follow the first line by a blank line. 568 569 570 ### Main content 571 572 The rest of the description elaborates and should provide context for the 573 change and explain what it does. 574 Write in complete sentences with correct punctuation, just like 575 for your comments in CUE. 576 Don't use HTML, Markdown, or any other markup language. 577 578 579 580 ### Referencing issues 581 582 The special notation "Fixes #12345" associates the change with issue 12345 in the 583 [CUE issue tracker](https://cuelang.org/issue/12345) 584 When this change is eventually applied, the issue 585 tracker will automatically mark the issue as fixed. 586 587 588 If the change is a partial step towards the resolution of the issue, 589 uses the notation "Updates #12345". 590 This will leave a comment in the issue 591 linking back to the change in Gerrit, but it will not close the issue 592 when the change is applied. 593 594 595 If you are sending a change against a subrepository, you must use 596 the fully-qualified syntax supported by GitHub to make sure the change is 597 linked to the issue in the main repository, not the subrepository. 598 All issues are tracked in the main repository's issue tracker. 599 The correct form is "Fixes cuelang/cue#159". 600 601 602 603 ## The review process 604 605 This section explains the review process in detail and how to approach 606 reviews after a change has been mailed. 607 608 609 610 ### Common beginner mistakes 611 612 When a change is sent to Gerrit, it is usually triaged within a few days. 613 A maintainer will have a look and provide some initial review that for first-time 614 contributors usually focuses on basic cosmetics and common mistakes. 615 These include things like: 616 617 618 - Commit message not following the suggested 619 format. 620 - The lack of a linked GitHub issue. 621 The vast majority of changes 622 require a linked issue that describes the bug or the feature that the change 623 fixes or implements, and consensus should have been reached on the tracker 624 before proceeding with it. 625 Gerrit reviews do not discuss the merit of the change, 626 just its implementation. 627 Only trivial or cosmetic changes will be accepted without an associated issue. 628 629 <!-- TODO 630 <li> 631 Change sent during the freeze phase of the development cycle, when the tree 632 is closed for general changes. 633 In this case, 634 a maintainer might review the code with a line such as `R=cue1.1`, 635 which means that it will be reviewed later when the tree opens for a new 636 development window. 637 You can add `R=cue1.XX` as a comment yourself 638 if you know that it's not the correct time frame for the change. 639 </li> 640 --> 641 642 <!-- 643 TODO 644 ### Trybots 645 646 After an initial reading of your change, maintainers will trigger trybots, 647 a cluster of servers that will run the full test suite on several different 648 architectures. 649 Most trybots complete in a few minutes, at which point a link will 650 be posted in Gerrit where you can see the results. 651 652 653 If the trybot run fails, follow the link and check the full logs of the 654 platforms on which the tests failed. 655 Try to understand what broke, update your patch to fix it, and upload again. 656 Maintainers will trigger a new trybot run to see 657 if the problem was fixed. 658 659 660 Sometimes, the tree can be broken on some platforms for a few hours; if 661 the failure reported by the trybot doesn't seem related to your patch, go to the 662 <a href="https://build.cuelang.org">Build Dashboard</a> and check if the same 663 failure appears in other recent commits on the same platform. 664 In this case, 665 feel free to write a comment in Gerrit to mention that the failure is 666 unrelated to your change, to help maintainers understand the situation. 667 668 --> 669 670 ### Reviews 671 672 The CUE community values very thorough reviews. 673 Think of each review comment like a ticket: you are expected to somehow "close" it 674 by acting on it, either by implementing the suggestion or convincing the 675 reviewer otherwise. 676 677 678 After you update the change, go through the review comments and make sure 679 to reply to every one. 680 You can click the "Done" button to reply 681 indicating that you've implemented the reviewer's suggestion; otherwise, 682 click on "Reply" and explain why you have not, or what you have done instead. 683 684 685 It is perfectly normal for changes to go through several round of reviews, 686 with one or more reviewers making new comments every time 687 and then waiting for an updated change before reviewing again. 688 This cycle happens even for experienced contributors, so 689 don't be discouraged by it. 690 691 692 ### Voting conventions 693 694 As they near a decision, reviewers will make a "vote" on your change. 695 The Gerrit voting system involves an integer in the range -2 to +2: 696 697 698 - **+2** The change is approved for being merged. 699 Only CUE maintainers can cast a +2 vote. 700 - **+1** The change looks good, but either the reviewer is requesting 701 minor changes before approving it, or they are not a maintainer and cannot 702 approve it, but would like to encourage an approval. 703 - **-1** The change is not good the way it is but might be fixable. 704 A -1 vote will always have a comment explaining why the change is unacceptable. 705 - **-2** The change is blocked by a maintainer and cannot be approved. 706 Again, there will be a comment explaining the decision. 707 708 ### Submitting an approved change 709 710 After the code has been +2'ed, an approver will 711 apply it to the master branch using the Gerrit user interface. 712 This is called "submitting the change". 713 714 715 The two steps (approving and submitting) are separate because in some cases maintainers 716 may want to approve it but not to submit it right away (for instance, 717 the tree could be temporarily frozen). 718 719 720 Submitting a change checks it into the repository. 721 The change description will include a link to the code review, 722 which will be updated with a link to the change 723 in the repository. 724 Since the method used to integrate the changes is Git's "Cherry Pick", 725 the commit hashes in the repository will be changed by 726 the submit operation. 727 728 729 If your change has been approved for a few days without being 730 submitted, feel free to write a comment in Gerrit requesting 731 submission. 732 733 734 735 <!-- 736 737 ### More information 738 739 TODO 740 In addition to the information here, the CUE community maintains a <a 741 href="https://cuelang.org/wiki/CodeReview">CodeReview</a> wiki page. 742 Feel free to contribute to this page as you learn more about the review process. 743 744 --> 745 746 747 ## Miscellaneous topics 748 749 This section collects a number of other comments that are 750 outside the issue/edit/code review/submit process itself. 751 752 753 754 ### Copyright headers 755 756 Files in the CUE repository don't list author names, both to avoid clutter 757 and to avoid having to keep the lists up to date. 758 Instead, your name will appear in the 759 [change log](https://cue.googlesource.com/cue/+log) and in the 760 [`CONTRIBUTORS`](../CONTRIBUTORS) file and perhaps the 761 [`AUTHORS`](../AUTHORS) file. 762 These files are automatically generated from the commit logs periodically. 763 The [`AUTHORS`](../AUTHORS) file defines who “The CUE 764 Authors”—the copyright holders—are. 765 766 767 New 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.) 787 Files in the repository are copyrighted the year they are added. 788 Do not update the copyright year on files that you change. 789 790 791 792 793 794 ### Troubleshooting mail errors 795 796 The most common way that the `git` `codereview` `mail` 797 command fails is because the e-mail address in the commit does not match the one 798 that you used during the registration process. 799 800 If you see something like... 801 802 803 ``` 804 remote: Processing changes: refs: 1, done 805 remote: 806 remote: ERROR: In commit ab13517fa29487dcf8b0d48916c51639426c5ee9 807 remote: ERROR: author email address XXXXXXXXXXXXXXXXXXX 808 remote: ERROR: does not match your user account. 809 ``` 810 811 you need to configure Git for this repository to use the 812 e-mail address that you registered with. 813 To change the e-mail address to ensure this doesn't happen again, run: 814 815 816 ``` 817 $ git config user.email email@address.com 818 ``` 819 820 Then change the commit to use this alternative e-mail address with this command: 821 822 823 ``` 824 $ git commit --amend --author="Author Name <email@address.com>" 825 ``` 826 827 Then retry by running: 828 829 830 ``` 831 $ git codereview mail 832 ``` 833 834 835 ### Quickly testing your changes 836 837 Running `go test ./...` for every single change to the code tree 838 is burdensome. 839 Even though it is strongly suggested to run it before 840 sending a change, during the normal development cycle you may want 841 to compile and test only the package you are developing. 842 843 844 In this section, we'll call the directory into which you cloned the CUE repository `$CUEDIR`. 845 As CUE uses Go modules, The `cue` tool built by 846 `go install` will be installed in the `bin/go` in your 847 home directory by default. 848 849 If you're changing the CUE APIs or code, you can test the results in just 850 this package directory. 851 852 ``` 853 $ cd $CUEDIR/cue 854 $ [make changes...] 855 $ go test 856 ``` 857 858 You don't need to build a new cue tool to test it. 859 Instead you can run the tests from the root. 860 861 ``` 862 $ cd $CUEDIR 863 $ go test ./... 864 ``` 865 866 To use the new tool you would still need to build and install it. 867 868 869 <!-- 870 TODO 871 ### Contributing to subrepositories (cuelang.org/x/...) 872 873 If you are contributing a change to a subrepository, obtain the 874 CUE package using `go get`. 875 For example, to contribute 876 to `cuelang.org/x/editor/vscode`, check out the code by running: 877 878 879 ``` 880 $ go get -d cuelang.org/editor/vscode 881 ``` 882 883 Then, change your directory to the package's source directory 884 (`$GOPATH/src/cuelang.org/x/oauth2`), and follow the 885 normal contribution flow. 886 887 --> 888 889 ### Specifying a reviewer / CCing others 890 891 <!-- 892 TODO: 893 894 Unless explicitly told otherwise, such as in the discussion leading 895 up to sending in the change, it's better not to specify a reviewer. 896 All changes are automatically CC'ed to the 897 <a href="https://groups.google.com/group/cue-codereviews">cue-codereviews@googlegroups.com</a> 898 mailing list. 899 If this is your first ever change, there may be a moderation 900 delay before it appears on the mailing list, to prevent spam. 901 902 --> 903 904 You can specify a reviewer or CC interested parties 905 using the `-r` or `-cc` options. 906 Both accept a comma-separated list of e-mail addresses: 907 908 909 ``` 910 $ git codereview mail -r joe@cuelang.org -cc mabel@example.com,math-nuts@swtch.com 911 ``` 912 913 914 ### Synchronize your client 915 916 While you were working, others might have submitted changes to the repository. 917 To update your local branch, run 918 919 920 ``` 921 $ git codereview sync 922 ``` 923 924 (Under the covers this runs 925 `git` `pull` `-r`.) 926 927 928 929 ### Reviewing code by others 930 931 As part of the review process reviewers can propose changes directly (in the 932 GitHub workflow this would be someone else attaching commits to a pull request). 933 934 You can import these changes proposed by someone else into your local Git repository. 935 On the Gerrit review page, click the "Download ▼" link in the upper right 936 corner, copy the "Checkout" command and run it from your local Git repo. 937 It will look something like this: 938 939 940 ``` 941 $ git fetch https://cue.googlesource.com/review refs/changes/21/13245/1 && git checkout FETCH_HEAD 942 ``` 943 944 To revert, change back to the branch you were working in. 945 946 947 ### Set up git aliases 948 949 The `git-codereview` command can be run directly from the shell 950 by typing, for instance, 951 952 953 ``` 954 $ git codereview sync 955 ``` 956 957 but it is more convenient to set up aliases for `git-codereview`'s own 958 subcommands, so that the above becomes, 959 960 961 ``` 962 $ git sync 963 ``` 964 965 The `git-codereview` subcommands have been chosen to be distinct from 966 Git's own, so it's safe to define these aliases. 967 To install them, copy this text into your 968 Git configuration file (usually `.gitconfig` in your home directory): 969 970 971 ``` 972 [alias] 973 change = codereview change 974 gofmt = codereview gofmt 975 mail = codereview mail 976 pending = codereview pending 977 submit = codereview submit 978 sync = codereview sync 979 ``` 980 981 982 ### Sending multiple dependent changes 983 984 Advanced users may want to stack up related commits in a single branch. 985 Gerrit allows for changes to be dependent on each other, forming such a dependency chain. 986 Each change will need to be approved and submitted separately but the dependency 987 will be visible to reviewers. 988 989 990 To send out a group of dependent changes, keep each change as a different commit under 991 the same branch, and then run: 992 993 994 ``` 995 $ git codereview mail HEAD 996 ``` 997 998 Make sure to explicitly specify `HEAD`, which is usually not required when sending 999 single changes. 1000