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.