github.com/elves/elvish@v0.15.0/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. 45 46 The release notes live in `website/blog`; the symlink `NEXT-RELEASE.md` at the 47 repo root always points to those of the next release. 48 49 ### Reference docs 50 51 Reference docs are interspersed in Go sources as comments blocks whose first 52 line starts with `//elvdoc` (and are hence called _elvdocs_). They can use 53 [Github Flavored Markdown](https://github.github.com/gfm/). 54 55 Elvdocs for functions look like the following: 56 57 ````go 58 //elvdoc:fn name-of-fn 59 // 60 // ```elvish 61 // name-of-fn $arg &opt=default 62 // ``` 63 // 64 // Does something. 65 // 66 // Example: 67 // 68 // ```elvish-transcript 69 // ~> name-of-fn something 70 // ▶ some-value-output 71 // ``` 72 73 func nameOfFn() { ... } 74 ```` 75 76 Generally, elvdocs for functions have the following structure: 77 78 - A line starting with `//elvdoc:fn`, followed by the name of the function. 79 Note that there should be no space after `//`, unlike all the other lines. 80 81 - An `elvish` code block describing the signature of the function, following 82 the convention [here](website/ref/builtin.md#usage-notation). 83 84 - Description of the function, which can be one or more paragraphs. The first 85 sentence of the description should start with a verb in 3rd person singular 86 (i.e. ending with a "s"), as if there is an implicit subject "this 87 function". 88 89 - One or more `elvish-transcript` code blocks showing example usages, which 90 are transcripts of actual REPL input and output. Transcripts must use the 91 default prompt `~>` and default value output indicator `▶`. You can use 92 `elvish -norc` if you have customized either in your `rc.elv`. 93 94 Place the comment block before the implementation of the function. If the 95 function has no implementation (e.g. it is a simple wrapper of a function from 96 the Go standard library), place it before the top-level declaration of the 97 namespace. 98 99 Similarly, reference docs for variables start with `//elvdoc:var`: 100 101 ```go 102 //elvdoc:var name-of-var 103 // 104 // Something. 105 ``` 106 107 Variables do not have signatures, and are described using a noun phrase. 108 Examples are not always needed; if they are, they can be given in the same 109 format as examples for functions. 110 111 ### Comment for unexported Go types and functions 112 113 In the doc comment for exported types and functions, it's customary to use the 114 symbol itself as the first word of the comment. For unexported types and 115 functions, this becomes a bit awkward as their names don't start with a capital 116 letter, so don't repeat the symbol. Examples: 117 118 ```go 119 // Foo does foo. 120 func Foo() { } 121 122 // Does foo. 123 func foo() { } 124 ``` 125 126 ## Generating code 127 128 Elvish uses generated code in a few places. As is the usual case with Go 129 projects, they are committed into the repo, and if you change the input of a 130 generated file you should re-generate it. 131 132 Use the standard command, `go generate ./...` to regenerate all files. 133 134 Dependencies of the generation rules: 135 136 - The `stringer` tool: Install with 137 `go get -u golang.org/x/tools/cmd/stringer`; 138 139 - An installed `elvish` in your PATH; 140 141 ## Formatting source files 142 143 Install [goimports](https://pkg.go.dev/golang.org/x/tools/cmd/goimports) to 144 format Go files, and [prettier](https://prettier.io/) to format Markdown files. 145 146 ```sh 147 go get golang.org/x/tools/cmd/goimports 148 npm install --global prettier@2.0.5 149 ``` 150 151 Once you have installed the tools, use `make style` to format Go and Markdown 152 files. If you prefer, you can also configure your editor to run these commands 153 automatically when saving Go or Markdown sources. 154 155 Use `make checkstyle` to check if all Go and Markdown files are properly 156 formatted. 157 158 ## Licensing 159 160 By contributing, you agree to license your code under the same license as 161 existing source code of elvish. See the LICENSE file.