github.com/kolbycrouch/elvish@v0.14.1-0.20210614162631-215b9ac1c423/CONTRIBUTING.md (about) 1 # Contributor's Manual 2 3 ## Human communication 4 5 The project lead is @xiaq, who is reachable in the user group most of the time. 6 7 If you intend to make user-visible changes to Elvish's behavior, it is good idea 8 to talk to him first; this will make it easier to review your changes. 9 10 On the other hand, if you find it easier to express your thoughts directly in 11 code, it is also completely fine to directly send a pull request, as long as you 12 don't mind the risk of the PR being rejected due to lack of prior discussion. 13 14 ## Testing changes 15 16 Write comprehensive unit tests for your code, and make sure that existing tests 17 are passing. Tests are run on CI automatically for PRs; you can also run 18 `make test` in the repo root yourself. 19 20 Respect established patterns of how unit tests are written. Some packages 21 unfortunately have competing patterns, which usually reflects a still-evolving 22 idea of how to best test the code. Worse, parts of the codebase are poorly 23 tested, or even untestable. In either case, discuss with the project lead on the 24 best way forward. 25 26 ### ELVISH_TEST_TIME_SCALE 27 28 Some unit tests depend on time thresholds. The default values of these time 29 thresholds are suitable for a reasonably powerful laptop, but on 30 resource-constraint environments (virtual machines, embedded systems) they might 31 not be enough. 32 33 Set the `ELVISH_TEST_TIME_SCALE` environment variable to a number greater than 1 34 to scale up the time thresholds used in tests. The CI environments use 35 `ELVISH_TEST_TIME_SCALE = 10`. 36 37 ## Documenting changes 38 39 Always document user-visible changes. 40 41 ### Release notes 42 43 Add a brief list item to the release note of the next release, in the 44 appropriate section. You can find the document at the root of the repo (called 45 `$version-release-notes.md`). 46 47 ### Reference docs 48 49 Reference docs are interspersed in Go sources as comments blocks whose first 50 line starts with `//elvdoc` (and are hence called _elvdocs_). They can use 51 [Github Flavored Markdown](https://github.github.com/gfm/). 52 53 Elvdocs for functions look like the following: 54 55 ````go 56 //elvdoc:fn name-of-fn 57 // 58 // ```elvish 59 // name-of-fn $arg &opt=default 60 // ``` 61 // 62 // Does something. 63 // 64 // Example: 65 // 66 // ```elvish-transcript 67 // ~> name-of-fn something 68 // ▶ some-value-output 69 // ``` 70 71 func nameOfFn() { ... } 72 ```` 73 74 Generally, elvdocs for functions have the following structure: 75 76 - A line starting with `//elvdoc:fn`, followed by the name of the function. 77 Note that there should be no space after `//`, unlike all the other lines. 78 79 - An `elvish` code block describing the signature of the function, following 80 the convention [here](website/ref/builtin.md#usage-notation). 81 82 - Description of the function, which can be one or more paragraphs. The first 83 sentence of the description should start with a verb in 3rd person singular 84 (i.e. ending with a "s"), as if there is an implicit subject "this 85 function". 86 87 - One or more `elvish-transcript` code blocks showing example usages, which 88 are transcripts of actual REPL input and output. Transcripts must use the 89 default prompt `~>` and default value output indicator `▶`. You can use 90 `elvish -norc` if you have customized either in your `rc.elv`. 91 92 Place the comment block before the implementation of the function. If the 93 function has no implementation (e.g. it is a simple wrapper of a function from 94 the Go standard library), place it before the top-level declaration of the 95 namespace. 96 97 Similarly, reference docs for variables start with `//elvdoc:var`: 98 99 ```go 100 //elvdoc:var name-of-var 101 // 102 // Something. 103 ``` 104 105 Variables do not have signatures, and are described using a noun phrase. 106 Examples are not always needed; if they are, they can be given in the same 107 format as examples for functions. 108 109 ### Comment for unexported Go types and functions 110 111 In the doc comment for exported types and functions, it's customary to use the 112 symbol itself as the first word of the comment. For unexported types and 113 functions, this becomes a bit awkward as their names don't start with a capital 114 letter, so don't repeat the symbol. Examples: 115 116 ```go 117 // Foo does foo. 118 func Foo() { } 119 120 // Does foo. 121 func foo() { } 122 ``` 123 124 ## Generating code 125 126 Elvish uses generated code in a few places. As is the usual case with Go 127 projects, they are committed into the repo, and if you change the input of a 128 generated file you should re-generate it. 129 130 Use the standard command, `go generate ./...` to regenerate all files. 131 132 Dependencies of the generation rules: 133 134 - The `stringer` tool: Install with 135 `go get -u golang.org/x/tools/cmd/stringer`; 136 137 - An installed `elvish` in your PATH; 138 139 ## Formatting source files 140 141 Install [goimports](https://pkg.go.dev/golang.org/x/tools/cmd/goimports) to 142 format Go files, and [prettier](https://prettier.io/) to format Markdown files. 143 144 ```sh 145 go get golang.org/x/tools/cmd/goimports 146 npm install --global prettier@2.0.5 147 ``` 148 149 Once you have installed the tools, use `make style` to format Go and Markdown 150 files. If you prefer, you can also configure your editor to run these commands 151 automatically when saving Go or Markdown sources. 152 153 Use `make checkstyle` to check if all Go and Markdown files are properly 154 formatted. 155 156 ## Licensing 157 158 By contributing, you agree to license your code under the same license as 159 existing source code of elvish. See the LICENSE file.