Contributing¶

Contributions are welcome, and they are greatly appreciated! Every little bit helps. Contributions do not have to be source code. There are many ways to contribute:

Report Bugs¶

Report bugs at the issue tracker.

If you are reporting a bug, please include:

Your operating system name and version.
Any details about your local setup that might be helpful in troubleshooting.
Detailed steps to reproduce the bug.
Ideally a minimal reproducible example.

Submit Feedback¶

Feedback can be submitted at the issue tracker as well.

If you are proposing a feature:

Explain in detail how it would work and why you would want it.
Keep the scope as narrow as possible, to make it easier to implement.
Remember that this is a volunteer-driven project, and that code contributions are welcome :)

Write Documentation¶

This project could always use more documentation, whether as part of the official cs-ranking docs, in docstrings, or even on the web in blog posts, articles, and such. For writing in-project documentation, the setup is similar to contributing code.

Contribute Code¶

Ready to get your hands dirty? Here’s how to set up cs-ranking for local development.

Fork the cs-ranking repository on GitHub.

Clone your fork locally:

$ git clone git@github.com:your_github_username_here/cs-ranking.git

Install your local copy using poetry. This is how you set up your fork for local development:
```
.. code-block:: bash
```
$ cd cs-ranking $ poetry install
Set up pre-commit for this repository, which was installed in the previous step. This will make sure that the changes you make adhere to our coding standards by checking formatting with black.

$ poetry run pre-commit install
You can run all pre-commit hooks on all files using
$ poetry run pre-commit run --all-files
The hooks will be run automatically when you run git commit.

Create a branch for your modifications:
```
$ git checkout -b some-name-for-the-branch
```
Now you can make your changes locally.
When you’re done making changes, check that the test suite still passes:
```
$ poetry run pytest
```
Fetch some coffee. This might take several minutes.
Commit your changes and push your branch to GitHub:
```
$ git add .
$ git commit
$ git push origin some-name-for-the-branch
```
Note that the second command will open an editor window in which you can write a commit message. Take care to use a good, descriptive commit message. If one of the pre-commit hooks fails, read the error output and make the necessary fixes. The fixes may already have been made before you (as is the case with black formatting), you just need to git add them.

If you do not understand why the hook fails, feel free to skip the hook for now:
```
$ git commit --no-verify
```
And mention the problem in the pull request. We will happily help you figure out the source of the problem.

Submit a pull request through the GitHub website. Keep the guidelines in the next section in mind.

Pull Request Guidelines¶

Before you submit a pull request, check that it meets these guidelines:

If you’re adding new functionality, you should also include tests and documentation for that functionality. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst. You can also add tests to the docstring:

def my_awesome_new_fn(input_number):
    """A function that does something and returns something.

    Some extended documentation.

    Python code prefixed by `>>>` within the documentation doubles as
    a test case:

    >>> print("Hello, world!")
    Hello, world!
    >>> my_awesome_fn(42)
    43
    """
    return input_number + 1

After submitting the pull request, keep an eye on travis and make sure that the tests pass for all supported Python versions.

Tips¶

To run a subset of tests:

$ poetry run pytest <path-to-file>

Help Wanted¶

Look through the GitHub issues. Anything tagged with “bug” and “help wanted” are particularly good places to get started. If you prefer to implement new features, the “enhancement” tag might be interesting as well.

Do Maintenance¶

These tasks are mostly done by project maintainers, though if you think they need to be done you can of course open an issue and ask for it. A pull request is even better.

Deploying¶

Make sure all your changes are committed (including an entry in HISTORY.rst). Then click on “Draft a new release” at the GitHub repository. GitHub Actions will ensure that the package is uploaded to PyPI.