Documentation: move contrib guide closer to source code, update README (

#66)

* Import contributing guide from checkbox-ng rst docs and convert it to markdown

* Point contributing section of the documentation to contributing guide in repo

* Add introduction, screenshots and link to contrib guide in README.md

* Adjust contrib guide to GitHub

* Adjust contrib guide section on providers

* Remove advice to prefix commit titles in contrib guide

Originally, prefixing commits with Add/Change/Remove/Fix was supposed to
help with changelog generation to get something easier to read. This
never materialized, as the rule is very loosely followed, and it does
not always make sense to apply it.

CONTRIBUTING.md

@@ -0,0 +1,198 @@
+# Contributing to Checkbox
+
+## Introduction
+
+This document provides the information needed to contribute to Checkbox
+and its providers.
+
+## General recommendations
+
+Setup your editor of choice to run
+[autopep8](https://pypi.org/project/autopep8/) on save. This helps keep
+everything passing [flake8](https://flake8.pycqa.org/en/latest/). The
+code doesn’t have to be pylint-clean, but running
+[pylint](https://www.pylint.org/) on your code may inform you about
+issues that could come up later in the review process.
+
+## Testing
+
+### Hacking on Checkbox and/or its providers
+
+If you want to hack on Checkbox or its providers, one method is to
+install everything you need in a Python virtual environment.
+
+Install the required tools:
+
+``` bash
+$ sudo apt install git python3-virtualenv
+```
+
+Prepare the development environment. If you are an external contributor and
+plan on submitting some changes, you will have to [fork the Checkbox repository
+first](https://docs.github.com/en/get-started/quickstart/fork-a-repo), and
+clone your own version locally. Otherwise:
+
+``` bash
+$ cd ~
+$ git clone git@github.com:canonical/checkbox.git
+```
+
+Create and activate the Python virtual environment:
+
+``` bash
+$ cd ~/checkbox/checkbox-ng
+$ ./mk-venv
+$ . ~/checkbox-ng/venv/bin/activate
+```
+
+Activate the base providers in the virtual environment from within the virtual
+environment:
+
+``` bash
+(venv) $ cd ~/checkbox/providers/resource/
+(venv) $ ./manage.py develop -d $PROVIDERPATH
+(venv) $ cd ~/checkbox/providers/base
+(venv) $ ./manage.py develop -d $PROVIDERPATH
+```
+
+Install the Checkbox support library in the virtual environment:
+
+``` bash
+(venv) $ cd ~/checkbox/checkbox-support
+(venv) $ ./setup.py install
+```
+
+You should now be able to run checkbox, select a test plan and run it:
+
+``` bash
+(venv) $ checkbox-cli
+```
+
+### Writing and running unit tests for Checkbox
+
+Writing unit tests for your code is strongly recommended. For functions
+with an easily defined input and output, use
+[doctest](https://docs.python.org/3/library/doctest.html). For more
+complex units of code use the standard [unittest
+library](https://docs.python.org/3/library/unittest.html).
+
+### Validate the providers
+
+Ensure the job and test plan definitions follow the correct syntax using
+the `validate` command:
+
+    $ ./manage.py validate
+
+### Writing and running unit tests for providers
+
+Run checks for code quality of provider hosted scripts and any unit
+tests for providers:
+
+    $ ./manage.py test
+
+## Version control recommendations
+
+### Commit title
+
+In general, try to follow [Chris Beams’
+recommendations](https://chris.beams.io/posts/git-commit/). In a
+nutshell:
+
+> -   Limit the length of the title to 50 characters
+> -   Begin title with a capital letter
+> -   Use the imperative mode (your title should always be able to
+>     complete the sentence “If applied, this commit will...”)
+
+### Commit message body
+
+Quoting again from Chris Beams’ article, use the body to explain what
+and why vs. how.
+
+Example:
+
+    Run Shellcheck on bin dir scripts
+
+    The test command to manage.py currently looks for python unittests
+    in the provider tests/ directory. This change searches the bin/
+    directory for files with suffix .sh and automatically generates
+    a unittest that runs the shellcheck command on the file.
+
+### Linking a pull request to a GitHub issue
+
+See the [GitHub documentation](https://docs.github.com/en/
+issues/tracking-your-work-with-issues/linking-a-pull-
+request-to-an-issue) for more information.
+
+### Splitting work in separate commits if required
+
+If the changes you provide affect different parts of the project, it is
+better to split them in different commits. This helps others when
+reviewing the changes, helps investigation later on if a problem is
+found and usually helps the original developer to better explain and
+organize his/her changes.
+
+For example, if you add a new screen to the Checkbox text user interface
+(TUI) and then modify Checkbox internals to work with this new screen,
+it is good to have one commit for the new screen, and one for the
+internals changes.
+
+Each commit should be stable, i.e. not introduce regressions or make
+tests fail. If two or more commits have to be used together, then they
+should become one commit.
+
+### Rework your changes
+
+Sometimes it is necessary to modify your changes (for instance after
+they have been reviewed by others). Instead of creating new commits with
+these new modifications, it is preferred to use Git features such as
+[rebase](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) to
+rework your existing commits.
+
+## Merge requests
+
+### General workflow
+
+Follow these steps to make a change to a Checkbox-related project.
+
+1. Check the [GitHub documentation](https://docs.github.com) on how to get
+   started. If you are a Checkbox contributor, you can clone the [Checkbox
+   repository](https://github.com/canonical/checkbox) directly; if you are an
+   external contributor, you will probably have to [fork the repository](https:
+   //docs.github.com/en/get-started/quickstart/fork-a-repo) first.
+
+1. If you created a fork, you need to [configure Git to sync your fork with the
+   original repository.](https://docs.github.com/en/get-started/quickstart/
+   fork-a-repo#configuring-git-to-sync-your-fork-with-the-original-repository)
+
+1. Create a branch and switch to it to start working on your changes.
+   You can use any branch name, but it is generally good to include the
+   GitHub issue number it relates to as well as a quick explanation of
+   what the branch is about:
+
+        $ git checkout -b 123456-invalid-session-content
+
+1. Work on your changes, test them, iterate, commit your work.
+
+1. Before sending your changes for review, make sure to rebase your
+   work using the most up-to-date data from the main repository:
+
+        $ git checkout main
+        # If you are a Checkbox contributor:
+        $ git fetch origin
+        # If you are an external contributor:
+        $ git fetch upstream
+        # Then, rebase your branch:
+        $ git checkout 123456-invalid-session-content
+        $ git rebase main
+        First, rewinding head to replay your work on top of it...
+        Applying: <your commits>
+
+1. [Push your changes](https://docs.github.com/en/get-started/using-git/
+   pushing-commits-to-a-remote-repository) to your GitHub repository.
+
+### Finally...
+
+Once enough people have reviewed and approved your work, it can be merged into
+the main branch of the main repository. Ask a member of the Checkbox team to do
+this. The branch should be then shortly automatically merged. The pull request
+status will then switch to “Merged”.

README.md

@@ -1,5 +1,26 @@
 Welcome to the Checkbox project source code repository!
 
+# What is Checkbox?
+
+[Checkbox] is a flexible test automation software. It’s the main tool used in the [Ubuntu Certification program].
+
+You can use Checkbox without any modification to check if your system is behaving correctly or you can develop your own set of tests to check your needs.
+
+Checkbox optionally generates test reports in different formats (HTML, JSON, text) that can be used to easily share the results of a test session.
+
+For more information, check the [official documentation].
+
+![Test report exported in HTML](checkbox-ng/docs/_images/checkbox-test-report.png)
+
+![Test selection screen in Checkbox](checkbox-ng/docs/_images/checkbox-snappy-3-select-jobs.png)
+
+# Getting started
+
+To get started, setup a test environment, run Checkbox and its providers, run the associated tests and share your contributions with everyone, please check the [contributing guide].
+
+
+# Content of the source code repository
+
 [Checkbox] is composed of many different parts. Each of them are stored in a different directory:
 
 ```
@@ -34,6 +55,9 @@ Here is a brief explanation about each part:
 - `metabox`: application to help test and validate Checkbox in different configurations using Linux containers or virtual machines
 
 [Checkbox]: https://checkbox.readthedocs.io/en/latest/
+[official documentation]: https://checkbox.readthedocs.io/en/latest/
+[contributing guide]: CONTRIBUTING.md
 [providers]: https://checkbox.readthedocs.io/en/latest/understanding.html#provider
+[Ubuntu Certification program]: https://ubuntu.com/certified
 [^1]: formerly known as "Checkbox provider" or `plainbox-provider-checkbox`
 [^2]: due to Checkbox flexibility, other providers can be used and might be hosted elsewhere (e.g. providers specific to private projects).