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.