How to Contribute

We’d love you to help us improve Kytos! Being a developer or not, your feedback is important for us to fix bugs, add new features and make it easier to create and share Network Applications.

To give us your feedback, check the most appropriate instructions in the next section. You can also contact us directly on the Slack channel.

Contributing Guidelines

Here are the guidelines we follow for different ways of contributing:

Got a Question or Problem?

If you have questions about how to use any component of the Kytos project, direct them to our Slack channel.

Found an Issue?

If you find a bug or a mistake in the documentation, you can help us by submitting an issue to our GitHub repository. Even better, you can submit a Pull Request to fix it. Before sharing a fix with the Kytos Community, please, check the Submission Guidelines section.

Want a Feature?

You can also request a new feature by submitting an issue to our GitHub repository. If you would like to implement a new feature, then consider what kind of change it is:

  • Major Changes that you wish to contribute to the project should be discussed first in our Slack channel, so that we can better coordinate our efforts, prevent work duplication, and help you craft the changes so they are successfully integrated into the project.

  • Small Changes can be crafted and submitted to the GitHub repository as Pull Requests.

Before contributing, please, check the Submission Guidelines section.

Want a Doc Fix?

You can either submit an issue or fix it by yourself. In either case, please, check the Submission Guidelines section. To update the documentation, read the section below.

Updating Documentation

Kytos subprojects have a docs folder that generates the documentation hosted in our website. To update it, follow these instructions:

  1. Install the required packages listed in requirements-docs.txt;

  2. In Python files, use Google-style docstrings (Napoleon documentation is also a useful resource);

  3. To generate the documentation, run make inside docs folder;

  4. Open docs/_build/dirhtml/index.html in your browser to check the output of your changes;

  5. Repeat steps 2 and 3 and refresh the page until you are satisfied with the results.

Tips and tricks

To automatically build the documentation and refresh the browser every time a file is changed:

  1. In the docs folder, run make livehtml;

  2. Go to http://127.0.0.1:8000/index.html.

Important

If you add or remove a page and see inconsistent results, try hitting ctrl+c, running make clean and then make livehtml again.

Submission Guidelines

Submitting an Issue

Before you submit your issue, search the archive to check whether the issue had already been reported. Use the specific subproject issue tracker of our GitHub repository. The more relevant information you provide, the faster contributors can solve the issue. From the information below, please, provide as much as possible:

  • Clear description about your problem: what is the expected outcome and what actually happened?

  • Error output or logs pasted in your issue or in a Gist. When pasting them in the issue, wrap it with three backticks: ``` so it renders nicely, like this;

  • Traffic files - if your issue is related to network traffic, attach as many traffic files as possible (i.e.: .pcap), as long as they don’t contain sensitive information;

  • Steps to reproduce - please inform all the steps to reproduce the error;

  • Motivation or use case - explain why this is a bug for you;

  • System details like what library or operating system you’re using and their versions;

  • Tags - tag your issue according to the version and issue type;

  • Related issues - are there similar issues?

  • Suggestions - if you can’t fix the bug yourself, perhaps you can point to what might be causing the problem (i.e.: line of code, commit);

  • Working version - if you specify the version that was working for you, we can find the code change that caused the issue and fix it faster.

For more information about GitHub issues, please read the GitHub’s Issues guide.

Submitting a Pull Request

If you’re able to patch the bug or add the feature yourself, fantastic! Before sharing your changes with Kytos community, be sure you’ve understood the license and signed our Contributor License Agreement (CLA).

For pull requests, Kytos subprojects use the forking workflow. You can follow this more detailed guide or the simplified steps below. In the next instructions, suppose you are going to fix a bug in the python-openflow subproject.

One-time setup for the subproject python-openflow:

  1. Open the python-openflow GitHub page and click in Fork;

  2. Clone your fork: git clone git@github.com:myuser/python-openflow.git;

  3. Add the official repository as upstream: git remote add upstream https://github.com/kytos/python-openflow.git.

For each pull request:

  1. Update your fork with the latest official code (based on this guide):

    1. git checkout master;

    2. git merge --ff-only upstream/master;

    3. git push;

  2. Create a branch to work on: git checkout -b fix-lorem-ipsum;

  3. Hack, commit, coffee, hack, …, commit (check code recommendations in the next list);

  4. Test your code and fix any issue: python3 setup.py test;

  5. Push the branch to GitHub: git push origin fix-lorem-ipsum;

  6. Visit your repository in GitHub and create a pull request with the push of a button.

For a better code and easier maintenance:

  • Include appropriate test cases to avoid bugs in the future;

  • Follow our Coding Style;

  • Avoid big commits if you can split them in meaningful smaller ones;

  • Commit your changes using clear, descriptive and on-point commit messages;

  • Write useful descriptions and titles;

  • Add comments to help guide the reviewer;

  • Add some screenshots for your front-end changes;

  • Think of a pull request as a product, with the author as the seller, and reviewers as customers;

  • Know that it’s difficult to review pull requests.

For more detailed tips on creating pull requests, read The (written) unwritten guide to pull requests.

That’s it! Thank you for your contribution!

Open Pull Requests

Once you’ve opened a pull request, a discussion will start around your proposed changes. Other contributors and users may chime in, but ultimately the decision is made by the maintainer(s). You may be asked to make some changes and, if so, add more commits to your branch and push them – they’ll automatically go into the existing pull request.

Code contribution steps review

  1. Fork the project & clone locally

  2. Create an upstream remote and sync your local copy before you branch

  3. Branch for each separate piece of work

  4. Do the work, write good commit messages, and follow the project coding style

  5. Push to your origin repository

  6. Create a new PR in GitHub

  7. Respond to any code review feedback

Blueprints

We have a type of document used to describe our architectural choices, called ‘blueprint’. This document is written for our developers and users and records all the main architectural decision proposals that were accepted or not in the kytos project. Blueprints are used to specify the details of any process, resource, and anything else that is desirable to be implemented, resulting in a major architectural change. Anyone can make enhancement proposals writing new blueprints, but first it is highly recommended that you take a look at our blueprints section to read about our past choices. Remember that this document is not just for you, but mainly for other developers.

Coding style

We follow pycodestyle, pydocstyle with Google-style docstrings and PEP 20. You can check The Best of the Best Practices (BOBP) Guide for Python for a summary. Besides, we use several linters.

Our build system checks both style and linter warnings and non-compliant pull requests won’t be merged. But don’t worry, python3 setup.py test will warn you about any problem in your code.

Signing the CLA

Please sign our Contributor License Agreement (CLA) before sending pull requests. For any code changes to be accepted, the CLA must be signed. It’s a quick process, we promise!