🎉 Thank you for taking the time to contribute! 🎉
The following is a set of guidelines for contributing to TenSEAL on GitHub. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.
What should I know before I get started?
Your Local Development Environment
If you have a question regarding release dates, how to use the library, and things like that, we suggest using the OpenMined Slack, you should get faster results in the slack channels than in a Github issue.
Make sure to ask your questions in the #lib_tenseal channel.
TenSEAL is a C++ library, all the core functionalities should be implemented in C++. Bindings to other languages such as Python should only have language specific functionalities. This make sure that the same features are available through all languages.
The roadmap of the project which can be found here is mainly drawn by the homomorphic encryption group in the crypto team at OpenMined.
This section guides you through submitting a bug report for TenSEAL. Following these guidelines helps maintainers and the community understand your report 📝, reproduce the behavior 💻 💻, and find related reports 🔎.
Before creating bug reports, please do a quick search on the existing issues to make sure no one has already reported it, as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible. Fill out the required template, the information it asks for helps us resolve issues faster.
Note: If you find a Closed issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one.
Bugs are tracked as GitHub issues. You can create a bug report here and provide the missing information in the provided template.
Explain the problem and include additional details to help maintainers reproduce the problem:
- Use a clear and descriptive title for the issue to identify the problem.
- Describe the exact steps which reproduce the problem in as many details as possible. For example, start by explaining the root cause of the problem, e.g. which line of code is throwing an error, or what command you ran so that the build crashed. If the bug is triggered by a code snippet, please put the whole source code, and not only the part that throws the error.
- Provide specific examples to demonstrate the steps. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you're providing snippets in the issue, use Markdown code blocks.
- Describe the behavior you observed after following the steps and point out what exactly is the problem with that behavior.
- Explain which behavior you expected to see instead and why.
Provide more context by answering these questions:
- Did the problem start happening recently (e.g. after updating to a new version of TenSEAL) or was this always a problem?
- If the problem started happening recently, can you reproduce the problem in an older version of TenSEAL? What's the most recent version in which the problem doesn't happen? You can download older versions of TenSEAL from the releases page.
- Can you reliably reproduce the issue? If not, provide details about how often the problem happens and under which conditions it normally happens.
Include details about your configuration and environment:
- Which version of TenSEAL are you using?
- What's the name and version of the OS you're using?
This section guides you through submitting an enhancement suggestion for TenSEAL, including completely new features and minor improvements to existing functionalities. Following these guidelines helps maintainers and the community understand your suggestion 📝 and find related suggestions 🔎.
Before creating enhancement suggestions, please do a quick search on the existing issues to make sure no one has already suggested it, as you might find out that you don't need to create one. When you are creating an enhancement suggestion, please include as many details as possible by filling out the required template, and including the steps that you imagine you would take if the feature you're requesting existed.
Enhancement suggestions are tracked as GitHub issues. We have many types of enhancement suggestions, ranging from documentation to new features, please open the most appropriate one for your need here
- Use a clear and descriptive title for the issue to identify the suggestion.
- Provide a step-by-step description of the suggested enhancement in as many details as possible.
- Provide specific examples to demonstrate the steps. Include copy/pasteable snippets which you use in those examples, as Markdown code blocks.
- Describe the current behavior and explain which behavior you expected to see instead and why.
- Explain why this enhancement would be useful to most TenSEAL users.
- Specify which version of TenSEAL you're using.
- Specify the name and version of the OS you're using.
Unsure where to begin contributing to TenSEAL? You can start by looking through Good first issue issues:
- Good first issue - issues which doesn't require a prior knowledge of the TenSEAL codebase.
We also suggest starting with the tutorials to get familiar with the user API and learn about the functionalities of the library.
TenSEAL can be developed locally. Check this section for instructions on how to setup your local development environment.
The process described here has several goals:
- Maintain TenSEAL's quality
- Fix problems that are important to users
- Engage the community in working toward the best possible TenSEAL
- Enable a sustainable system for TenSEAL's maintainers to review contributions
Please follow these steps to have your contribution considered by the maintainers:
- Follow all instructions in the pull request template
- Follow the styleguides
- 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.
While the prerequisites above must be satisfied prior to having your pull request reviewed, the reviewer(s) may ask you to complete additional design work, tests, or other changes before your pull request can be ultimately accepted.
Before being able to make any code contribution, you need to be able to setup your local environment to make changes, build the new library, as well as running the tests to make sure previous functionalities are still working, and to tests new ones.
Note: You can always use our Docker images for a ready to use environment. We provide images for different Python versions on every release or code change in the master branch, so it's also easy to try older non-released versions.
After cloning TenSEAL into your machine, or cloning one of your forks, you must make sure to fetch thrid party libraries that TenSEAL depends on, you can do that by running:
$ git submodule init
$ git submodule updateYou can build and install the library (with Python bindings) locally by running:
$ pip install -r requirements_dev.txt
$ pip install .This will trigger the build of the C++ library as well as the Python bindings. Please refer to this section for more information about the dependencies required to build TenSEAL.
Note: You can skip the building step if you are testing the library using Bazel, as it make sure the library is built before running the tests.
If you use Bazel, you can do that pretty easily by running:
$ bazel test --test_output=all --spawn_strategy=standalone //tests/cpp/...Otherwise, you can always build the tests using CMake for the C++ test, and run them as follows:
$ cmake . -D BUILD_TEST=TRUE
$ make && make testThe Python tests can be ran using pytest:
$ pytest -v tests/You can also start the tests with Bazel:
$ bazel test --test_output=all --spawn_strategy=standalone //tests/python/...All C++ code must be formatted based on our clang-format config file. You can easily setup that into your prefered IDE, so that formatting is applied as you code.
All Python code must be formatted using black. You can easily setup that into your prefered IDE, so that formatting is applied as you code.
TBD
This section lists the labels we use to help us track and manage issues and pull requests. Most labels are used across all OpenMined repositories, but some are specific to OpenMined/TenSEAL.
GitHub search makes it easy to use labels for finding groups of issues or pull requests you're interested in. For example, you might be interested in open issues across OpenMined/TenSEAL which are labeled as bugs or perhaps open pull requests in OpenMined/TenSEAL which haven't been reviewed yet. To help you find issues and pull requests, each label is listed with search links for finding open items with that label in OpenMined/TenSEAL. We encourage you to read about other search filters which will help you write more focused queries.
The labels are loosely grouped by their purpose, but it's not required that every issue have a label from every group or that an issue can't have more than one label from the same group.
| Label name | Description |
|---|---|
| API | Related to the API |
| Build | Related to the build of the package |
| Good first issue 🎓 | Perfect for beginners, welcome to OpenMined! |
| Priority: 1 - Immediate 🔥 | Must be fixed immediately and cannot wait |
| Priority: 2 - High 😰 | Should be fixed as quickly as possible, ideally within the current or following sprint |
| Priority: 3 - Medium 😒 | Should be fixed soon, but there may be other pressing matters that come first |
| Priority: 4 - Low 😎 | Should only be scheduled if it's important relative to other issues |
| Severity: 1 - Critical 🔥 | Causes a failure of the complete software system, subsystem or a program within the system |
| Severity: 2 - High 😰 | Does not cause a failure, but causes the system to be incorrect, incomplete, or inconsistent |
| Severity: 3 - Medium 😒 | Does not cause a failure, impair usability, or interfere with the system |
| Severity: 4 - Low 😎 | An aesthetic issue or is the result of non-conformance to a standard |
| Status: Abandoned 😭 | This was assigned to someone but is not in active development |
| Status: Available 👋 | Available for assignment, who wants it? |
| Status: Blocked ✖️ | Cannot work on this because of some other incomplete work |
| Status: Completed ✔️ | Finished with all expected deliverables |
| Status: In Progress 🌟 | This is actively being worked on |
| Status: Investigating 🔍 | Something we are looking in to, but not currently in active development |
| Status: Review Needed 🙋 | This needs someone to approve, deny, comment, or request changes |
| Status: Stale 🍞 | Been open for a while with no activity |
| Type: Bug 🐛 | Some functionality not working in the codebase as intended |
| Type: Discussion 🔈 | When further discussion and debate is required |
| Type: Documentation 📚 | Improvements or additions in documentation for some file, feature, or codebase |
| Type: Epic 🤙 | Describes a large amount of functionality that will likely be broken down into smaller issues |
| Type: Improvement 📈 | Performance improvement not introducing a new feature or requiring a major refactor |
| Type: New Feature ➕ | Introduction of a completely new addition to the codebase |
| Type: Question ❔ | Question about implementation or some technical aspect |
| Type: Refactor 🔨 | A complete overhaul of a file, feature, or codebase |
| Type: Research 🔬 | When further investigation into a subject is required |
| Type: Testing 🧪 | Add testing or improving existing testing of a file, feature, or codebase |
| duplicate | This issue or pull request already exists |