Contributing

CAMP is an open source tool and we welcome any kind of contributions, from fixing typos in the documentation to fixing bugs in the code. We explain here:

• What the todo list
• The overall layout of the source code;
• How to contribute to the documentation;
• How to build and modify the code

TODO List

• Features

  • A “version” command that displays the version of CAMP, but also the version of Z3, Python and the underlying OS.

  • Add option to the generate command to only estimate the number of configurations”

• Refactorings

  • Rewrite the YAML codec so that it parses test reports and returns the proper CAMP object instead of a dictionary.

  • Refactor the YAML parser so that all the boilerplate code about ignored/missing entries is written once and for all.

  • Spread the use to tests.commons in the test for CAMP generate and CAMP realize

• Configuration

  • Find a way to have documentation available per version, when a new version is released.

  • Restore testing multiple versions of python and Z3 on Circle-CI

The Source Code

Below is the overall organization of the source tree. The two main directories are camp and docs, which contain the Python source code and the documentation, respectively.

$ tree -L 1 .
├── camp                # Python Source code
├── Dockerfile
├── docs                # Documentation
├── LICENSE
├── modules             # Other tools, linked to the projects
├── README.md 
├── requirements.txt    # Python dependencies
├── samples             # Example of how to use CAMP
├── setup.py            # Packaging
└── tests               # Python tests cases

The Documentation

This is the source directory of the CAMP companion website. It basically contains the documentation.

This a statuuuic website, which is generated by Jekyll behind the scene.

Here is the structure of the directory:

• assets contains the static resources, such as images, or PDF files that we want to provide access to.

• data/ contains a single YAML file that describes the structures of navigation bar, that is what entries exists and the pages they point to.

• pages contains all the pages (except index.md). This is simply a convention to avoid a mess at the root level.

• _layouts/ contains the HTML template that we have overriden from the chosen them (minimal).

• _sass/ contains the CSS template that we have overriden from the chosen them (minimal).

How run it on your local machine?

If you make changes to the site, you can visualize them by serving the site on your machine. We assume that Ruby and bundler are already installed.

$> bundle update
$> bundle install
$> bundle exec jekyll serve

The website is now accessible on your own machine.

Adding New Pages?

We’ve chosen to place new pages in the pages directory and link them to other pages or to the menu by editing the _data/menu.ymlas follows:

- name: CAMP
  url: index

- name: Getting Started
  url: pages/getting_started
  children:
    - name: Installation
      url: pages/installation

- name: Case Studies
  url:
  children:
    - name: XWiki
      url: pages/xwiki
    - name: CityGo
      url: pages/citygo
    - name: Awesome Case-study     # <-- Here I added a new menu entry
      url: pages/awesome           # No file extension

- name: Other
  url:
  children:
    - name: Publications
      url: pages/publications

Building and Developing

Installation

If you want to modify the CAMP source code, I recommend that you install it locally, including the Z3 solver, as explained in the setup instructions.

I recommend you first create virtual environment before to install CAMP and its Python dependencies, to avoid polluting your own Python installation.

$ virtualenv -p /usr/python2.7 .venv2.7
$ source .venv2.7/bin/activate

Then use pip install -eto install it in development mode, so that you see any changes you make in the source code when you run camp from the command line.

$ pip install -e .

Tests

The tests folder contains the tests—as the same says. You can use the standard setup script to run the tests as follow:

$ python setup.py test

I however recommend to use the Green tests runner that simplify visualizing results in the command line.

$ green -qfvv tests

It will stop after the first test that fails and capture the standard output if any.

Making Releases

We tried to automate as much as possible the release process. Here is the process:

1. Add and commit your changes locally.
2. Update the version number in the file camp/__init__.py
3. Update the ChangeLog in the documentation, in the file docs/pages/changelog.md
4. Add and commit these new changes locally.
5. Tag this new commit with the version number as annotation as follows:

   $ git tag -a v4.2.5 -m "Releasing Version 4.2.5"
   

6. Push these commit and the new tag using the command:

   $ git push --follow-tags
   

The CI server will detect the new tag and build and push new Docker images on Dockerhub.