👍🎉 First off, thanks for taking the time to contribute! 🎉👍
The following is a set of guidelines for contributing to volesti, which are hosted in the GeomScale Organization 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.
- Prerequisites (how to start)
- Testing the development branch of volesti (get the tools ready)
- Fork volesti repository (this is your repo now!)
- Working with volesti (get ready to contribute)
- Modify the branch (implement, implement, implement)
- Pull request (the joy of sharing)
- Review (ok this is not an exam)
- git (see Getting Started with Git)
- 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
Clone the repository,
git clone [email protected]: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 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
You can check here to see more installation guide.
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.
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.
- login on
GitHub - go to volesti repository
- click the 'Fork' button
- choose your profile
- wait
- ready to contribute!
More info: Forking Projects
Go out of volesti directory
cd ..
clone your repository and checkout develop branch
git clone [email protected]:vissarion/volume_approximation.git volesti_fork
cd volesti_fork
git remote add upstream [email protected]:GeomScale/volesti.git
git fetch upstream
git checkout upstream/develop
git branch -vv
see commits
git log
gitk
For now you should see exactly the same commits as in volesti repository.
Volesit is using the GitFlow 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.
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!
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
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 are placed in the test directory and use the 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.
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
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.
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.