CONTRIBUTING.md

Introduction

First off, thanks for using and considering contributing to byexample.

byexample is an open source project that aims other projects to have high quality documentation and tests.

It is for the community and we love to receive contributions from our community.

This guideline will help you to go through the process of contributing from forking and reviewing the code to doing your first pull request.

It is not just contribute code

Supporting a new language or extending an existing one it is always welcome. Check this how to.

But it is not just contribute code.

Is byexample producing a hard-to-debug diff or did you found a bug? Creating an issue in github is as important as writing new code.

Do you like to write? Write a blog or post in the social medias (I hope for the good :)

Do you want to contribute but you are not sure where to start? Pick an issue from here; the issues with the label good first issue is what you are looking for.

Do not worry to do mistakes

Everyone was new some day. Do your best and ask for help if you need it.

Modules: the preferred way

We love to extend byexample adding new modules.

Instead of editing the internal Parser class, extend it through a parser that can be loaded on the fly using modules (read this how to if you didn't)

Instead of editing the internal Runner class, try to a Concern.

If you find that a feature would be cool and the current Concern's interface (a set of hooks) is not enough, open an issue and propose an extension for Concern.

In this way your contributions can be merged and shipped in the next release without worrying to be incompatible with previous versions.

But if you have the feeling that something cool is missing, don't be afraid and talk about it.

Warming up

Go to github and make a fork.

Then, you clone it in your computer:

$ git clone https://github.com/<your github username>/byexample.git     # byexample: +skip

Regression tests

Now, run a small regression tests to make sure you have a good baseline.

$ make lib-test     # byexample: +skip
<...>
[PASS] <...>

You can run all the examples in the documentation (this will require Ruby installed for the examples written in Ruby)

$ make docs-test     # byexample: +skip
<...>
[PASS] <...>

The full set of test that only require python and a shell can be executed with a single command:

$ make test     # byexample: +skip
<...>
[PASS] <...>

To run the rest of the tests that will require ruby, gdb, gcc and others, we do:

$ make docker-test  # byexample: +skip
<...>
[PASS] <...>

As you may guessed, this will create a docker container with all the needed dependencies.

The first time will take a lot of time because docker will be creating the container.

Run a single test case

Use byexample of course!

To run the examples of in a doc or source file, just point to it.

For example, if you fixed a bug in the Parser and you want to check that you are not introducing any new issue, run its tests in this way:

$ byexample -l python byexample/parser.py     # byexample: +skip

If the test that you want to run requires an interpreter that you don't have installed (like ruby or gdb), you can start a docker container and run byexample there:

$ make docker-shell     # byexample: +skip

How to submit a contribution

If your contribution is quite small, open a pull request directly.

If you think that you need some brainstorming first before working on it or you may have some question, open a ticket first. Leave the pull request for later.

Try to give as much as context as you can.

If it is a bug, explain what you did and what should be the correct answer. If it is a new idea, explain why do you think it would be cool? Extra points if you provide examples!

No one knows everything so it is ok to ask but expect some delay in the answer, sometimes some questions are not as easier as you think!

Be patient and respectful in both sides: if you are doing the question or you are answering.

And don't forget, before asking, try to see if you can figure out by your own. It is ok not to know things, but people will appreciate you efforts.