github.com/markusbkk/elvish@v0.0.0-20231204143114-91dc52438621/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 91 [`rc.elv`](https://elv.sh/ref/command.html#rc-file). 92 93 Place the comment block before the implementation of the function. If the 94 function has no implementation (e.g. it is a simple wrapper of a function from 95 the Go standard library), place it before the top-level declaration of the 96 namespace. 97 98 Similarly, reference docs for variables start with `//elvdoc:var`: 99 100 ```go 101 //elvdoc:var name-of-var 102 // 103 // Something. 104 ``` 105 106 Variables do not have signatures, and are described using a noun phrase. 107 Examples are not always needed; if they are, they can be given in the same 108 format as examples for functions. 109 110 ### Comment for unexported Go types and functions 111 112 In the doc comment for exported types and functions, it's customary to use the 113 symbol itself as the first word of the comment. For unexported types and 114 functions, this becomes a bit awkward as their names don't start with a capital 115 letter, so don't repeat the symbol. Examples: 116 117 ```go 118 // Foo does foo. 119 func Foo() { } 120 121 // Does foo. 122 func foo() { } 123 ``` 124 125 ## Generating code 126 127 Elvish uses generated code in a few places. As is the usual case with Go 128 projects, they are committed into the repo, and if you change the input of a 129 generated file you should re-generate it. 130 131 Use the standard command, `go generate ./...` to regenerate all files. 132 133 Some of the generation rules depend on the `stringer` tool. Install with 134 `go install golang.org/x/tools/cmd/stringer@latest`. 135 136 ## Code hygiene 137 138 Some basic aspects of code hygiene are checked in the CI. 139 140 ### Formatting 141 142 Install [goimports](https://pkg.go.dev/golang.org/x/tools/cmd/goimports) to 143 format Go files, and [prettier](https://prettier.io/) to format Markdown files. 144 145 ```sh 146 go install golang.org/x/tools/cmd/goimports@latest 147 npm install --global prettier@2.3.1 148 ``` 149 150 Once you have installed the tools, use `make style` to format Go and Markdown 151 files. If you prefer, you can also configure your editor to run these commands 152 automatically when saving Go or Markdown sources. 153 154 Use `make checkstyle` to check if all Go and Markdown files are properly 155 formatted. 156 157 ### Linting 158 159 Install [staticcheck](https://staticcheck.io): 160 161 ```sh 162 go install honnef.co/go/tools/cmd/staticcheck@2021.1 163 ``` 164 165 The other linter Elvish uses is the standard `go vet` command. Elvish doesn't 166 use golint since it is 167 [deprecated and frozen](https://github.com/golang/go/issues/38968). 168 169 Use `make lint` to run `staticcheck` and `go vet`. 170 171 ### Spell checking 172 173 Install [codespell](https://github.com/codespell-project/codespell) to check 174 spelling: 175 176 ```sh 177 pip install --user codespell==2.1.0 178 ``` 179 180 Use `make codespell` to run it. 181 182 ### Running all checks 183 184 Use this command to run all checks: 185 186 ```sh 187 make test checkstyle lint codespell 188 ``` 189 190 You can put this in `.git/hooks/pre-push` to ensure that your published commits 191 pass all the checks. 192 193 ## Licensing 194 195 By contributing, you agree to license your code under the same license as 196 existing source code of elvish. See the LICENSE file.