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.