Installing and contributing#

Installing BIPES on your own setup is easy and straight forward, just follow the quick start.

After you played around for a while and you wishes to contribute to the project, read forking and contributing, where a handy way to make good contributions is presented.

The platform has been tested on Ubuntu, Fedora and OpenSuse, and also inside a WSL2 container. A Dockerfile is planned, but is not ready yet.

Quick start#

The video below shows the cloning and installation walkthrough:

First, install git and make in your system, then clone the repository:

git clone https://github.com/BIPES/BIPES

Use the cd command to change to the repository:

cd BIPES

And install BIPES with the included installation script:

make

Follow the prompts, the script will install the dependencies, fetch and compile some JavaScript libraries and run a development server on port 5001.

Just enter http://127.0.0.1:5001/ide in the browser after the script prompts “Running BIPES in development mode”. This development mode is a special state that forbids the browser from caching the platform, allowing changes made to it to be applied instantaneously.

To stop running, press Ctrl+C in the terminal.

To run it again in development mode, at the same directory, do

make run

In development mode, different languages are accessed by including the language code to the link, e.g. http://127.0.0.1:5001/ide-de loads the IDE in German.

Additional options, such as how to use PostgreSQL instead of SQLite as the database engine, are described at release and deploy.

Windows notes#

On Windows, please use WSL2.

Install the usual stuff like make and git in WSL, then proceed with make in the repository root directory.

Forking and contributing#

As BIPES is a fully open source project and it’s understood that users and companies desire to make their own BIPES platform for different purposes, having that in mind, users face two common issues:

  1. The fork quickly gets behind the BIPES:master and cannot automatically fetch and merge from it.

  2. Cannot contribute to BIPES:master due commits use-case specific or not relevant to the codebase.

Luckily, git has powerful tools to easily work around these issues, but first, step up your understanding of git branches before continuing.

Forking#

To solve the first issue, the first step is to fork into your GitHub account, then clone to your computer using your ssh key connected to GitHub and in a terminal do:

git clone git@github.com:YOUR_ACCOUNT/BIPES.git

And include BIPES:master as the upstream source, so you can fetch new commits.

git remote add upstream git@github.com:BIPES/BIPES.git

To check the branches, use git branch -a to list all branches, or just the new upstream sources with git fetch upstream.

Then, to include new commits from BIPES:master, fetch upstream with:

git fetch upstream master

Which will fetch and automatically merge if no conflict is found. If there is conflicts between the branches, a merge tool is used to manually merge the code between version. A easy to use merge tool is Gnome Meld.

After installing your preferred merge tool, do:

git mergetool

The command will recursively open all files with merge conflicts, so that you can solve them and reach a conflict-free version. Also, it might complain that you have not configured it yet, but do not worry since it will automatically find and use a installed merge tool.

Contributing#

To solve the second issue, a new branch will be required, where only the desired commits will be included.

The first set is to fetch from all sources to make sure everything is up-to-date:

git fetch --all

Then, create a branch from BIPES:master, where you will commit only the desired commits. Replace YOUR_BRANCH with a concise name that best describes the included commits, like “BIPES_i18n” for translations commits and “BIPES_newPlots” for new plotting options.

git checkout -b YOUR_BRANCH upstream/master

Then cherry-pick the commits you want to include, where COMMIT_CODE is the code of the commit.

git cherry-pick COMMIT_CODE

Now do some quality control by testing the branch version. If everything is working as expected, push to remote.

git push -u origin YOUR_BRANCH

Finally, open a pull request from the branch YOUR_BRANCH to the target BIPES:master, and we will review it for you.