Revision 77c446f0b39d67228621d4ba217d5369dee75ad4 authored by Vissarion Fisikopoulos on 07 December 2020, 15:42:37 UTC, committed by GitHub on 07 December 2020, 15:42:37 UTC
1 parent 95f86eb
CONTRIBUTING.md
# Contributing to `volesti`
:+1::tada: First off, thanks for taking the time to contribute! :tada::+1:
The following is a set of guidelines for contributing to volesti,
which are hosted in the [GeomScale Organization](https://github.com/GeomScale) on GitHub.
These are mostly guidelines, not rules.
Use your best judgment, and feel free to propose changes to this document in a pull request.
## Table of Contents
* [Prerequisites (how to start)](#prerequisites--how-to-start-)
* [Testing the development branch of volesti (get the tools ready)](#testing-the-development-branch-of-volesti--get-the-tools-ready-)
* [Fork volesti repository (this is your repo now!)](#fork--volesti-repository--this-is-your-repo-now--)
+ [Verify if your fork works (optional)](#verify-if-your-fork-works--optional-)
* [Working with volesti (get ready to contribute)](#working-with-volesti--get-ready-to-contribute-)
+ [GitFlow workflow](#gitflow-workflow)
+ [Create new branch for your work](#create-new-branch-for-your-work)
+ [Verify your new branch (optional)](#verify-your-new-branch--optional-)
* [Modify the branch (implement, implement, implement)](#modify-the-branch--implement--implement--implement-)
+ [Tests](#tests)
+ [Push](#push)
* [Pull request (the joy of sharing)](#pull-request--the-joy-of-sharing-)
* [Review (ok this is not an exam)](#review--ok-this-is-not-an-exam-)
## Prerequisites (how to start)
* git (see [Getting Started with Git](https://help.github.com/en/github/using-git/getting-started-with-git-and-github))
* a compiler to run tests - gcc, clang, etc.
* configured GitHub account
Other helpful links:
* http://git-scm.com/documentation
* https://help.github.com/articles/set-up-git
* https://opensource.com/article/18/1/step-step-guide-git
## Testing the development branch of volesti (get the tools ready)
Clone the repository,
git clone git@github.com:GeomScale/volume_approximation.git volesti
cd volesti
git branch -vv
the last command should tell you that you are in `develop` branch.
To compile the `C++` code you have to specify the path to external library `liblpsolve55.so/dll/dylib` (see [here](doc/cpp_interface.md) more detail), by running, in folder test:
mkdir -p test/build && cd test/build
cmake -DLP_SOLVE=_PATH_TO_LIB_FILE_ ..
# e.g. on linux: cmake -DLP_SOLVE=/usr/lib/lp_solve/liblpsolve55.so ..
make
Run the tests,
ctest -jK
where `K` is the number of CPU threads. By adding the option `--verbose` to `ctest` you get more information about the tests,
*e.g.* time per test, volume computed and the name of the polytope or convex body.
If everything works for you, you may move forward.
## Fork volesti repository (this is your repo now!)
You can't work directly in the original volesti repository, therefore you should create your fork of this library.
This way you can modify the code and when the job is done send a pull request to merge your changes with the original
repository.
1. login on `GitHub`
2. go to [volesti repository](https://github.com/GeomScale/volume_approximation)
3. click the 'Fork' button
4. choose your profile
5. wait
6. ready to contribute!
More info: [Forking Projects](https://guides.github.com/activities/forking/)
### Verify if your fork works (optional)
Go out of `volesti` directory
cd ..
clone your repository and checkout develop branch
git clone git@github.com:vissarion/volume_approximation.git volesti_fork
cd volesti_fork
git checkout develop
git branch -vv
git pull
see commits
git log
gitk
For now you should see exactly the same commits as in `volesti` repository.
## Working with volesti (get ready to contribute)
### GitFlow workflow
Volesit is using the [GitFlow](http://nvie.com/posts/a-successful-git-branching-model/) workflow.
It's because it is very well suited to collaboration and scaling the development team.
Each repository using this model should contain two main branches:
* master - release-ready version of the library
* develop - development version of the library
and could contain various supporting branches for new features and hotfixes.
As a contributor you'll most likely be adding new features or fixing bugs in the development version of the library.
This means that for each contribution you should create a new branch originating from the develop branch,
modify it and send a pull request in order to merge it, again with the develop branch.
### Create new branch for your work
Make sure you're in develop branch running
git branch -vv
you should see
Now you should pick a name for your new branch that doesn't already exist.
The following checks for existing remote branches
git branch -a
Alternatively, you can check them on `GitHub`.
Assume you want to add some new functionality (i.e. a new feature) for example a new sampling algorithm. Then you have
to create a new branch e.g. `feature/the_fastest_sampling_algo_ever`
Create new local branch
git branch feature/the_fastest_sampling_algo_ever
git checkout feature/the_fastest_sampling_algo_ever
push it to your fork
git push -u my_fork feature/the_fastest_sampling_algo_ever
Note that the `-u` switch also sets up the tracking of the remote branch. Your new branch now is created!
### Verify your new branch (optional)
Now with the command
git branch -vv
you see
Note that without the `-u` switch you wouldn't see the tracking information for your new branch.
Alternatively, your newly created remote branch is also available on GitHub
## Modify the branch (implement, implement, implement)
Before contributiong to a library by adding a new feature, or a bugfix, or improving documentation,
it is always wise to interact with the community of developers, for example by opening an issue.
### Tests
Tests are placed in the `test` directory and use the [doctest](https://github.com/onqtam/doctest) library.
It is recommended to add new test whenever you contribute a new functionality/feature.
Also if your contribution is a bugfix then consider adding this case to the test-suite.
### Push
At the end, push your changes to the remote branch
git push my_fork feature/the_fastest_sampling_algo_ever
or if your local branch is tracking the remote one, just
git push
## Pull request (the joy of sharing)
After pushing your work you should be able to see it on `GitHub`.
Click "Compare and pull request" button or the "New pull request" button.
Add title and description
and click the "Create pull request" button.
## Review (ok this is not an exam)
After creating a pull request your code will be reviewed. You can propose one or more reviewers
by clicking on the "Reviewers" button
If there are no objections your changes will be merged.
Otherwise you'll see some comments under the pull request and/or under specific lines of your code.
Then you have to make the required changes, commit them and push to your branch.
Those changes will automatically be a part of the same pull request. This procedure will be repeated until the code
is ready for merging.
If you're curious how it looks like you may see one of the open or closed
[pull requests](https://github.com/GeomScale/volume_approximation/pulls).
Computing file changes ...
