Thanks for taking the time to contribute!
The following is a set of guidelines for contributing to PyElastica. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.
TLTR! I need three-line summary!!
- Reporting bugs
- Suggesting enhancements
- Your first code contribution
- Side projects
- Pull requests
- Have questions about the source code
- I found bugs! - Please ensure the bug was not already reported on issues. If you cannot find an open issue addressing the problem, open a new one. Be sure to include clear title and description and appropriate labels. To speed up the process, we recommend including how to reproduce behavior along with expected behavior.
- I'm struggling in using PyElastica for my project! - Please open the issue with the label
help wantedand explain the details of the problem and issue. We would gladly reach you to assist. - How can I contribute!? - If you already wrote the patch, you can open a
pull requestwith the changes to theupdate_<version>branch. Ensure the code passes the formatting and styles. The PR should clearly describe the problem and solution. Include all relevant issue numbers if applicable.
First create the fork repository and clone to your local machine. We provide requirements.txt to include all the dependencies.
$ pip install -r requirements.txtNote: Make sure that PyElastica is not installed using pip.
We will create an update_<version> branch every couple of months, and will release the branch once all related issues are resolved.
Every patch will be merged into the update branch only to organize major changes.
Each version will have an associated collection of issues as Milestones.
If you have a patch, make a pull request to the update_<version> branch.
We recommend making the branch name start with related issue number (ex. 1_<branch name>).
Following these guidelines helps maintainers and the community to understand the problem.
- Please check if a related bug is not already issued.
- Use a clear and descriptive title for the issue to identify the problem. Also, include appropriate labels.
- Reporting how to reproduce a bug and details of the problem (constraint, connection, etc.) could help developers to resolve the issue. Including code is also a good idea.
- Explain the expected behavior and why.
- Include additional details as much as possible.
- Including screenshots or animated gifs also helps.
- Which version of PyElastica and dependencies was used.
- If relevant, what version and OS was used.
- Link any related issues using
#<issue number>.
Note: If you find a Closed issue that seems like the same thing that you're experiencing, please open a new issue and include a link to the original (closed) issue in the description.
This section guides you through submitting an enhancement suggestion, including new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion.
- Use a clear and descriptive title for the issue to identify the suggestion. Also include appropriate labels:enhancements.
- If the problem is related to performance or memory, please include a performance profiling that you are reporting.
- Please include as many details as possible. If you already have a suggestion patch, please include the link to the changes.
- Which version of PyElastica and dependencies was used.
- If relevant, what version and OS was used.
- Include a description of the current behavior and explain expected behavior.
- Explain why this enhancement would be useful.
If you are unsure regarding how to start contributing to PyElastica, you can look through good first issue and help wanted labels.
Also, you might find TODO or FIXME marks in various places in the code with brief descriptions.
- Beginner issues - issues that should only require a few lines of code, and a test or two.
- Help wanted issues - issues which should be a bit more involved and might need some discussion.
Once you find the issue that you are interested in, please leave a comment that you would like to resolve the issue. If you leave some questions in the comment, we will provide more detailed descriptions.
We also have many related projects in separate repositories that utilize the PyElastica as a core library.
Please follow these steps to have your contribution considered by the maintainers:
-
Follow the styleguides
-
Before you submit your pull request run pytests and make sure that all tests pass.
In order to run pytest, run the following line from the top directory:
python3 -m pytest -
After you submit your pull request, verify that all status checks are passing
What if the status checks are failing?
If a status check is failing, and you believe that the failure is unrelated to your change, please leave a comment on the pull request explaining why you believe the failure is unrelated. A maintainer will re-run the status check for you. If we conclude that the failure was a false positive, then we will open an issue to track that problem with our status check suite.
The reviewer(s) may ask you to complete additional tests or changes before your pull request can be accepted.
Ask any question about how to use PyElastica and detail implementation in the issue with label:question.
- Limit the first line to 72 characters or less
- Reference issues and pull requests liberally after the first line
- When only changing documentation, include
[ci skip]in the commit title
We use flake8 and Black for python style.
You can install flake8 using pip:
pip install flake8==3.8.3
You can install black using pip:
pip install black
In order to format the code:
make all
Note: Format/refactoring patches that are not anything substantial to the context or functionality will likely be rejected.
We follow NumPy documentation guidelines for PyElastica documentation.