Contributing¶

This documents guides you through how to make improvements to the bln library by installing its source code and suggesting improvements.

Create a fork ¶

Start by visiting our project’s repository at github.com/biglocalnews/bln-python-client and creating a fork. You can learn how from GitHub’s documentation.

Clone the fork ¶

Now you need to make a copy of your fork on your computer using GitHub’s cloning system. There are several methods to do this, which are covered in the GitHub documentation.

A typical terminal command will look something like the following, with your username inserted in the URL.

git clone git@github.com:your-username/bln-python-client.git

or

gh repo clone your-username/bln-python-client

Install dependencies ¶

You should change directory into folder where you code was downloaded.

cd bln-python-client

The pipenv package manager can install all of the Python tools necessary to run and test our code. Since you’ll be using the special tools we need as part of code development, add the --dev flag.

pipenv install --dev

Now install pre-commit to run a battery of automatic quick fixes against your work.

pipenv run pre-commit install

Create a branch ¶

Next will we create a branch in your local repository where you an work without disturbing the mainline of code.

You can do this by running a line of code like the one below. You should substitute a branch that summarizes the work you’re trying to do.

git checkout -b your-branch-name

For instance, if you were trying to fix an upload bug, you might name it something like this:

git checkout-b upload-bug-fix

Perform you work ¶

Now you do your thing. Make the necessary changes to the code until you get the job done.

Run tests ¶

Before you submit your work for inclusion in the project, you should run our tests to identify bugs. Testing is implemented via pytest. Run the tests with the following.

make test

If any errors, arise, carefully read the traceback message to determine what needs to be repaired.

Push to your fork ¶

Once you’re happy with your work and the tests are passing, you should commit your work and push it to your fork.

git commit -am "Describe your work here"
git push origin your-branch-name

The final step is to submit a pull request to the main respository, asking the maintainers to consider integrating your patch. GitHub has a short guide that can walk you through the process. You should tag your issue number in the request so that they are linked in GitHub’s system.