diff options
| -rw-r--r-- | contributing.txt | 70 | ||||
| -rw-r--r-- | docs/markdown/Contributing.md | 144 | ||||
| -rw-r--r-- | docs/markdown/index.md | 20 | ||||
| -rw-r--r-- | docs/sitemap.txt | 1 |
4 files changed, 162 insertions, 73 deletions
diff --git a/contributing.txt b/contributing.txt index 094c5e6..b1c015c 100644 --- a/contributing.txt +++ b/contributing.txt @@ -1,70 +1,4 @@ Contributing to the Meson build system -There are two simple ways to submit your patches. The preferred way is -to send a github pull request. Small changes can also be sent as -patches as emails to the Meson mailing list. - - -Python Coding style - -Meson follows the basic Python coding style. Additional rules are the -following: - -- indent 4 spaces, no tabs ever -- indent meson.build files with two spaces -- try to keep the code as simple as possible -- contact the mailing list before embarking on large scale projects - to avoid wasted effort -- all new features must come with a test (or several if it is - a big feature) - -Meson uses Flake8 for style guide enforcement. The Flake8 options for -the project are contained in setup.cfg. - -To run Flake8 on your local clone of Meson: - - $ python3 -m pip install flake8 - $ cd meson - $ flake8 - -C/C++ coding style - -Meson has a bunch of test code in several languages. The rules for -those are simple. - -- indent 4 spaces, no tabs ever -- brace always on the same line as if/for/else/function definition - - -External dependencies - -The goal of Meson is to be as easily usable as possible. The user -experience should be "get Python3 and Ninja, run", even on -Windows. Unfortunately this means that we can't have dependencies on -projects outside of Python's standard library. This applies only to -core functionality, though. For additional helper programs etc the use -of external dependencies may be ok. If you feel that you are dealing -with this kind of case, please raise the issue on the mailing list -first. - - -What not to contribute? - -There are a few things that people seem to want to add to Meson but which -are not there by design and will not be added either. - -The first one is defining your own functions or a generalized for loop. -These are bad because they would make Meson's DSL Turing complete. The -second feature is a Make backend. - -The FAQ has specific information why these two features will not be -added to Meson: http://mesonbuild.com/FAQ.html - -Merge requests adding either of these two features will be automatically -rejected. Please save everyone's time (especially your own) and don't start -working on these features. - - -Do I need to sign a CLA? - -No. All contributions are welcome. +Contribution instructions can be found [on the +website](http://mesonbuild.com/Contributing.html). diff --git a/docs/markdown/Contributing.md b/docs/markdown/Contributing.md new file mode 100644 index 0000000..354bf62 --- /dev/null +++ b/docs/markdown/Contributing.md @@ -0,0 +1,144 @@ +--- +short-description: Contributing to Meson +... + +# Contributing to Meson + +A large fraction of Meson is contributed by people outside the core +team. This documentation explains some of the design rationales of +Meson as well as how to create and submit your patches for inclusion +to Meson. + +Thank you for your interest in participating to the development. + +## Submitting patches + +All changes must be submitted as [pull requests to +Github](https://github.com/mesonbuild/meson/pulls). This causes them +to be run through the CI system. All submissions must pass a full CI +test run before they are even considered for submission. + +## Tests + +All new features must come with automatic tests that throughly prove +that the feature is working as expected. Similarly bug fixes must come +with a unit test that demonstrates the bug, proves that it has been +fixed and prevents the feature from breaking in the future. + +Sometimes it is difficult to create a unit test for a given bug. If +this is the case, note this in your pull request. We may permit bug +fix merge requests in these cases. This is done on a case by case +basis. Sometimes it may be easier to write the test than convince the +maintainers that one is not needed. Exercise judgment and ask for help +in problematic cases. + +## Documentation + +The `docs` directory contains the full documentation that will be used +to generate [the Meson web site](http://mesonbuild.com). Every change +in functionality must change the documentation pages. In most cases +this means updating the reference documentation page but bigger +changes might need changes in other documentation, too. + +All new functionality needs to have a mention in the release +notes. These features should be written in standalone files in the +`docs/markdown/snippets` directory. The release manager will combine +them into one page when doing the release. + +## Python Coding style + +Meson follows the basic Python coding style. Additional rules are the +following: + +- indent 4 spaces, no tabs ever +- indent meson.build files with two spaces +- try to keep the code as simple as possible +- contact the mailing list before embarking on large scale projects + to avoid wasted effort + +Meson uses Flake8 for style guide enforcement. The Flake8 options for +the project are contained in setup.cfg. + +To run Flake8 on your local clone of Meson: + +```console +$ python3 -m pip install flake8 +$ cd meson +$ flake8 +``` + +## C/C++ coding style + +Meson has a bunch of test code in several languages. The rules for +those are simple. + +- indent 4 spaces, no tabs ever +- brace always on the same line as if/for/else/function definition + + + +## External dependencies + +The goal of Meson is to be as easily usable as possible. The user +experience should be "get Python3 and Ninja, run", even on +Windows. Unfortunately this means that we can't have dependencies on +projects outside of Python's standard library. This applies only to +core functionality, though. For additional helper programs etc the use +of external dependencies may be ok. If you feel that you are dealing +with this kind of case, please contact the developers first with your +use case. + +## Turing completeness + +The main design principle of Meson is that the definition language is +not Turing complete. Any change that would make Meson Turing complete +is automatically rejected. In practice this means that defining your +own functions inside `meson.build` files and generalised loops will +not be added to the language. + +## Do I need to sign a CLA in order to contribute? + +No you don't. All contributions are welcome. + +## No lingering state + +Meson operates in much the same way as functional programming +languages. It has inputs, which include `meson.build` files, values of +options, compilers and so on. These are passed to a function, which +generates output build definition. This function is pure, which means that: + + - for any given input the output is always the same + - running Meson twice in a row _always_ produce the same output in both runs + +The latter one is important, because it enforces that there is no way +for "secret state" to pass between consecutive invocations of +Meson. This is the reason why, for example, there is no `set_option` +function even though there is a `get_option` one. + +If this were not the case, we could never know if the build output is +"stable". For example suppose there were a `set_option` function and a +boolean variable `flipflop`. Then you could do this: + +```meson +set_option('flipflop', not get_option('flipflop')) +``` + +This piece of code would never converge. Every Meson run would change +the value of the option and thus the output you get out of this build +definition would be random. + +Meson does not permit this by forbidding these sorts of covert channels. + +There is one exception to this rule. Users can call into external +commands with `run_command`. If the output of that command does not +behave like a pure function, this problem arises. Meson does not try +to guard against this case, it is the responsibility of the user to +make sure the commands they run behave like pure functions. + +## Environment variables + +Environment variables are like global variables, except that they are +also hidden by default. Envvars should be avoided whenever possible, +all functionality should be exposed in better ways such as command +line switches. + diff --git a/docs/markdown/index.md b/docs/markdown/index.md index 81c17ff..5f42cc7 100644 --- a/docs/markdown/index.md +++ b/docs/markdown/index.md @@ -6,9 +6,13 @@ render-subpages: false ## Overview -Meson is an open source build system meant to be both extremely fast, and, even more importantly, as user friendly as possible. +Meson is an open source build system meant to be both extremely fast, +and, even more importantly, as user friendly as possible. -The main design point of Meson is that every moment a developer spends writing or debugging build definitions is a second wasted. So is every second spent waiting for the build system to actually start compiling code. +The main design point of Meson is that every moment a developer spends +writing or debugging build definitions is a second wasted. So is every +second spent waiting for the build system to actually start compiling +code. ## Features @@ -22,12 +26,18 @@ The main design point of Meson is that every moment a developer spends writing o ## Community -There are two main methods of connecting with other Meson developers. The first one is the mailing list, which is hosted at [Google Groups](https://groups.google.com/forum/#!forum/mesonbuild). +There are two main methods of connecting with other Meson +developers. The first one is the mailing list, which is hosted at +[Google Groups](https://groups.google.com/forum/#!forum/mesonbuild). -The second way is via IRC. The channel to use is `#mesonbuild` at [Freenode](https://freenode.net/). +The second way is via IRC. The channel to use is `#mesonbuild` at +[Freenode](https://freenode.net/). ## Development -All development on Meson is done on [GitHub project](https://github.com/mesonbuild/meson). For further info look into the `contributing.txt` file that comes with Meson's source checkout. +All development on Meson is done on [GitHub +project](https://github.com/mesonbuild/meson). Instruction on +contributing can be found on the [contribution page](Contributing.md). + You do not need to sign a CLA to contribute to Meson. diff --git a/docs/sitemap.txt b/docs/sitemap.txt index 77a4e6f..b7ee136 100644 --- a/docs/sitemap.txt +++ b/docs/sitemap.txt @@ -90,5 +90,6 @@ index.md Use-of-Python.md Users.md Using-multiple-build-directories.md + Contributing.md legal.md Videos.md |