CONTRIBUTING.md

   1 # How to contribute
   2
   3 mruby is an open-source project which is looking forward to each contribution.
   4 Contributors agree to license their contribution(s) under MIT license.
   5
   6 ## Your Pull Request
   7
   8 To make it easy to review and understand your change please keep the following
   9 things in mind before submitting your pull request:
  10
  11 - Work on the latest possible state of **mruby/master**
  12 - Create a branch which is dedicated to your change
  13 - Test your changes before creating a pull request (`rake test`)
  14 - If possible write a test case which confirms your change
  15 - Don't mix several features or bug-fixes in one pull request
  16 - Create a meaningful commit message
  17 - Explain your change (i.e. with a link to the issue you are fixing)
  18 - Use mrbgem to provide non ISO features (classes, modules and methods) unless
  19   you have a special reason to implement them in the core
  20
  21 ## pre-commit
  22
  23 A framework for managing and maintaining multi-language `pre-commit` hooks.
  24 `pre-commit` can be [installed](https://pre-commit.com/#installation) with `pip`, `curl`, `brew` or `conda`.
  25
  26 You need to first install `pre-commit` and then install the `pre-commit` hooks with `pre-commit install`.
  27 Now `pre-commit` will run automatically on git commit!
  28
  29 It's usually a good idea to run the hooks against all the files when adding new hooks (usually `pre-commit`
  30 will only run on the changed files during git hooks). Use `pre-commit run --all-files` to check all files.
  31
  32 To run a single hook use `pre-commit run --all-files <hook_id>`
  33
  34 To update use `pre-commit autoupdate`
  35
  36 Sometimes you might need to skip one or more hooks which can be done with the `SKIP` environment variable.
  37
  38 `$ SKIP=yamllint git commit -m "foo"`
  39
  40 For convenience, we have added `pre-commit run --all-files`, `pre-commit install` and `pre-commit autoupdate`
  41 to both the Makefile and the Rakefile. Run them with:
  42
  43 - `make check` or `rake check`
  44 - `make checkinstall` or `rake checkinstall`
  45 - `make checkupdate` or `rake checkupdate`
  46
  47 To configure `pre-commit` you can modify the config file [.pre-commit-config.yaml](.pre-commit-config.yaml).
  48 We use [GitHub Actions](.github/workflows/lint.yml) to run `pre-commit` on every pull request.
  49
  50 ### pre-commit quick links
  51
  52 - [Quick start](https://pre-commit.com/#quick-start)
  53 - [Usage](https://pre-commit.com/#usage)
  54 - [pre-commit autoupdate](https://pre-commit.com/#pre-commit-autoupdate)
  55 - [Temporarily disabling hooks](https://pre-commit.com/#temporarily-disabling-hooks)
  56
  57 ## Docker
  58
  59 We have both a `Dockerfile` and `docker-compose.yml` files in the repository root.
  60 You can run these with the command line or use
  61 [Docker Desktop](https://www.docker.com/products/docker-desktop/).
  62
  63 The Docker image is running Debian bullseye with Ruby and Python installed.
  64 You can build the Docker image with:
  65
  66 `$ docker-compose build test`
  67
  68 So far we just have one service: `test`. Running the default `docker-compose`
  69 command will create the Docker image, spin up a container and then build and
  70 run all mruby tests.
  71
  72 The default `docker-compose` command is:
  73
  74 `$ docker-compose -p mruby run test`
  75
  76 You can also use Make or Rake to run the default `docker-compose`
  77 command from above:
  78
  79 - `make composetest`
  80 - `rake composetest`
  81
  82 List your Docker images with:
  83
  84 ```console
  85 $ docker images
  86 REPOSITORY   TAG       IMAGE ID       CREATED          SIZE
  87 mruby-test   latest    ec60f9536948   29 seconds ago   1.29GB
  88 ```
  89
  90 You can also run any custom `docker-compose` command which will override
  91 the default. For example to run `pre-commit run --all-files` type:
  92
  93 `$ docker-compose -p mruby run test pre-commit run --all-files`
  94
  95 For convenience, you can also run `pre-commit` with:
  96
  97 - `make composecheck`
  98 - `rake composecheck`
  99
 100 The bonus of running `pre-commit` with `docker-compose` is that you won't need
 101 to install `pre-commit` and the hooks on your local machine. And that also
 102 means you won't need to install `brew`, `conda` or `pip`.
 103
 104 Note limitation: currently running `pre-commit` with `docker-compose` we
 105 skip the `check-executables-have-shebangs` hook.
 106
 107 Two more examples of custom `docker-compose` commands are:
 108
 109 - `$ docker-compose -p mruby run test ls`
 110 - `$ docker-compose -p mruby run test rake doc:api`
 111
 112 If you want to test using a different `docker-compose` YAML config file you
 113 can use the `-f` flag:
 114
 115 `$ docker-compose -p mruby -f docker-compose.test.yml run test`
 116
 117 - <https://docs.docker.com/compose/>
 118 - <https://docs.docker.com/engine/reference/commandline/cli/>
 119
 120 ## Spell Checking
 121
 122 We are using `pre-commit` to run [codespell](https://github.com/codespell-project/codespell)
 123 to check code for common misspellings. We have a small custom dictionary file [codespell.txt](.github/linters/codespell.txt).
 124
 125 ## Coding conventions
 126
 127 How to style your C and Ruby code which you want to submit.
 128
 129 ### C code
 130
 131 The core part (parser, bytecode-interpreter, core-lib, etc.) of mruby is
 132 written in the C programming language. Please note the following hints for your
 133 C code:
 134
 135 #### Comply with C99 (ISO/IEC 9899:1999)
 136
 137 mruby should be highly portable to other systems and compilers. For this it is
 138 recommended to keep your code as close as possible to the C99 standard
 139 (<http://www.open-std.org/jtc1/sc22/WG14/www/docs/n1256.pdf>).
 140
 141 Visual C++ is also an important target for mruby (supported version is 2013 or
 142 later). For this reason features that are not supported by Visual C++ may not
 143 be used (e.g. `%z` of `strftime()`).
 144
 145 NOTE: Old GCC requires `-std=gnu99` option to enable C99 support.
 146
 147 #### Reduce library dependencies to a minimum
 148
 149 The dependencies to libraries should be kept to an absolute minimum. This
 150 increases the portability but makes it also easier to cut away parts of mruby
 151 on-demand.
 152
 153 #### Insert a break after the function return value:
 154
 155 ```c
 156 int
 157 main(void)
 158 {
 159   ...
 160 }
 161 ```
 162
 163 ### Ruby code
 164
 165 Parts of the standard library of mruby are written in the Ruby programming
 166 language itself. Please note the following hints for your Ruby code:
 167
 168 #### Comply with the Ruby standard (ISO/IEC 30170:2012)
 169
 170 mruby is currently targeting to execute Ruby code which complies to ISO/IEC
 171 30170:2012 (<https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=59579>),
 172 unless there's a clear reason, e.g. the latest Ruby has changed behavior from ISO.
 173
 174 ## Building documentation
 175
 176 ### mruby API
 177
 178 - [YARD](https://yardoc.org/) - YARD is a documentation generation tool for the Ruby programming language
 179 - [yard-mruby](https://rubygems.org/gems/yard-mruby) - Document mruby sources with YARD
 180 - [yard-coderay](https://rubygems.org/gems/yard-coderay) - Adds coderay syntax highlighting to YARD docs
 181
 182 ### C API
 183
 184 - [Doxygen](https://www.doxygen.nl/) - Generate documentation from source code
 185 - [Graphviz](https://graphviz.org/) - Graphviz is open source graph visualization software