Contribution Guide¶
Thank you for choosing to spend your time contributing to the Eddington platform. Contributors are the living, beating heart of any open-source project, and we really appreciate each and every contribution made to our code-base, big or small.
Here is a relatively short guide on how to contribute code to Eddington. Please follow the next steps carefully when making a pull request.
Step 1 – Writing Your Code¶
Like any other open-source project in Github, contribution to Eddington is done via a pull-request (PR). Fork the desired repository, open a feature branch, and write your code in it.
When writing code, please pay attention that you:
- Make sure your master branch is up-to-date with the latest changes in the Eddington platform, and make your feature branch based upon it. This will help you avoid merge conflicts.
- Write your code clearly, with self-explainable variables, functions and classes.
- Reuse existing code when possible.
- Document new functions, classes, and modules (especially if they’re public).
The code reviews you’ll receive would often address the following guidelines, as well as any existing design issues.
Step 2 – Testing Your Code In Development Mode¶
While at the moment Eddington-GUI does not have unit tests, you can still run it in development environment in order to test the new feature you’ve been added.
In order to do so, follow the following steps:
- Create a virtual environment in order to isolate your working space from outside dependencies that can affect Eddington-GUI.
- Install Briefcase using
pip install briefcase
- Run Eddington-GUI in dev mode using
briefcase dev
Note
Running briefcase dev
will install automatically the required dependencies
for Eddington-GUI. If you wish to install this dependencies without running the
program, use briefcase dev --no-run
Step 3 – Cleaning Your Code¶
Writing a working code can sometimes be really hard, but writing a clean code is always harder.
Here on the Eddington platform we believe that code should be clean, and we want to make sure that writing clean code is as easy as possible. We do that by using automatic tools that would help you achieve that along the way.
We use state-of-the-art static code analysis tools such as black, flake8, pylint, mypy, pydocstyle, etc. Statue is orchestrating all these tools by running each of them on all of our code-base.
In order to use Statue, follow the next steps:
- Run
pip install statue
. - Run
statue install
. If needed, this command will install missing packages. - Go to the main repository directory and run
statue run --context format
. This will change your code to fit styling guidelines. Save the changes in a commit or append them to an existing commit. - Run
statue run
again (now without any arguments) and it will check if there are any issues that it wasn’t able to solve on its own. If there are any errors, fix them. - Save all changes in a commit or append them to an existing commit.
You may find some of the errors presented by those tools tedious or irrelevant, but rest assured that we take those errors seriously.
If you think that in a specific line an error should be ignored (using # noqa
or # pylint: disable
for example), please make sure that this skip is justified
before applying it.
Step 4 - Testing Your Code in Production Mode¶
In order to make sure that your code works in production mode, follow the following steps:
- Run
briefcase create
. This command will create a production environment for Eddington-GUI - Run
briefcase run
. This command will run Eddington-GUI in production mode.
Note
Once you did these too steps once, you can use briefcase update
to re-install
your code and briefcase update -d
to reinstall dependencies. After yout do
that, run briefcase run
again to re-run Eddington-GUI.
Step 5 – Adding Yourself to the Acknowledgment File¶
We acknowledge each and every one of our contributors in docs/acknowledgment.rst. Add your name to the contributors file, keeping alphabetical order.
Step 6 – Receiving a Code Review and Merging¶
Push the branch and open a PR. We will make our best efforts to review your PR as soon as possible.
Once you receive a code-review, address the issues presented to you by changing the code or commenting back. Once all the issues are resolved, your PR will be merged to master!