We would love for you to contribute to LambdaPool and help make it even better than it is today! As a contributor, here are the guidelines we would like you to follow:
- Code of Conduct
- Question or Problem?
- Issues and Bugs
- Feature Requests
- Submission Guidelines
- Development Setup
- Coding Rules
- Commit Message Guidelines
Help us keep the project open and inclusive. Please read and follow our Code of Conduct.
Do not open issues for general support questions as we want to keep GitHub issues for bug reports and feature requests. You've got much better chances of getting your question answered on Stack Overflow.
Stack Overflow is a much better place to ask questions since:
- there are thousands of people willing to help on Stack Overflow
- questions and answers stay available for public viewing so your question / answer might help someone else
- Stack Overflow's voting system assures that the best answers are prominently visible.
To save your and our time, we will systematically close all issues that are requests for general support and redirect people to Stack Overflow.
If you would like to chat about the question in real-time, you can reach out via our slack channel.
If you find a bug in the source code, you can help us by submitting an issue to our GitHub Repository. Even better, you can submit a Pull Request with a fix.
You can request a new feature by submitting an issue to our GitHub Repository. If you would like to implement a new feature, please submit an issue with a proposal for your work first, to be sure that we can use it. Please consider what kind of change it is:
- For a Major Feature, first open an issue and outline your proposal so that it can be discussed. This will also allow us to better coordinate our efforts, prevent duplication of work, and help you to craft the change so that it is successfully accepted into the project.
- Small Features can be crafted and directly submitted as a Pull Request.
Before you submit an issue, please search the issue tracker, maybe an issue for your problem already exists and the discussion might inform you of workarounds readily available.
We want to fix all the issues as soon as possible, but before fixing a bug we need to reproduce and confirm it. In order to reproduce bugs, we will systematically ask you to provide a minimal reproduction. Having a minimal reproducible scenario gives us a wealth of important information without going back & forth to you with additional questions.
A minimal reproduction allows us to quickly confirm a bug (or point out a coding problem) as well as confirm that we are fixing the right problem.
We will be insisting on a minimal reproduction scenario in order to save maintainers time and ultimately be able to fix more bugs. Interestingly, from our experience users often find coding problems themselves while preparing a minimal reproduction. We understand that sometimes it might be hard to extract essential bits of code from a larger code-base but we really need to isolate the problem before we can fix it.
Unfortunately, we are not able to investigate / fix bugs without a minimal reproduction, so if we don't hear back from you we are going to close an issue that doesn't have enough info to be reproduced.
Before you submit your Pull Request (PR) consider the following guidelines:
-
Search GitHub for an open or closed PR that relates to your submission. You don't want to duplicate effort.
-
Be sure that an issue describes the problem you're fixing, or documents the design for the feature you'd like to add. Discussing the design up front helps to ensure that we're ready to accept your work.
-
Fork the rorodata/lambdapool repo.
-
Make your changes in a new git branch:
git checkout -b fixes-issue-id master
-
Create your patch, including appropriate test cases.
-
Follow our Coding Rules.
-
Ensure that all tests pass.
-
Commit your changes using a descriptive commit message that follows our commit message conventions.
git commit -p
-
Push your branch to GitHub:
git push origin fixes-issue-id
-
In GitHub, send a pull request to
lambdapool:master.
- If we suggest changes then:
-
Make the required updates.
-
Re-run the test suite ensure tests are still passing.
-
Rebase your branch and force push to your GitHub repository (this will update your Pull Request):
git rebase master -i git push -f
-
That's it! Thank you for your contribution!
After your pull request is merged, you can safely delete your branch and pull the changes from the main (upstream) repository:
-
Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows:
git push origin --delete fixes-issue-id
-
Check out the master branch:
git checkout master -f
-
Delete the local branch:
git branch -D myfixes-issue-id
-
Update your master with the latest upstream version:
git pull --ff upstream master
The development machine should have Python 3.6 installed. It is recommended to setup the development using virtualenv with/without virtualenvwrapper. Setting them up is out of the scope of this document and can be referred from above linked project websites.
The project dependencies can be installed using:
(venv) lambdapool $ pip install -r requirements.txt
...In order to develop lambdapool, it must be installed in editable mode so as to keep on testing the modifications as they are developed:
(venv) lambdapool $ pip install -e .
...We prefer using pytest as our testing suite, pytest-flakes as our linting tool and pytest-cov as our code coverage tool.
(venv) lambdapool $ pip install -r dev-requirements.txt
...It is recommended to always run the tests before filing any Pull Request. A bash script exists in the project for the convenience of the developers which runs the tests along with flakes checks and calculates code coverage.
(venv) lambdapool $ ./runtests.sh
...To ensure consistency throughout the source code, keep these rules in mind as you are working:
- All features or bug fixes must be tested.
- All public API methods must be documented.
- The functionality implemented must have proper type annotations.
- We follow Google's Python Style Guide to an extent. The focus should always be on code readability and future extensibility rather than on rules.
- The code must not fail flake checks.
- Code coverage must maintained well, although this may not mean that the tests are appropriately written.
- Add the appropriate change to the the topmost subheading in the CHANGELOG
The seven rules of a great Git commit message
Keep in mind: This has all been said before.
- Separate subject from body with a blank line
- Limit the subject line to 50 characters
- Capitalize the subject line
- Do not end the subject line with a period
- Use the imperative mood in the subject line
- Wrap the body at 72 characters
- Use the body to explain what and why vs. how
- Present tense or imperative tense both are okay in subject lines
For example:
Summarize changes in around 50 characters or less
More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit and the rest of the text as the body. The
blank line separating the summary from the body is critical (unless
you omit the body entirely); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.
Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.
Further paragraphs come after blank lines.
- Bullet points are okay, too
- Typically a hyphen or asterisk is used for the bullet, preceded
by a single space, with blank lines in between, but conventions
vary here
If you use an issue tracker, put references to them at the bottom,
like this:
Resolves: #123
See also: #456, #789
Reference: https://chris.beams.io/posts/git-commit/