Hello and thank you for taking the time to contribute! 👋 🎉
The following is a set of guidelines for contributing to the Spark Dgraph Connector (SDC) on GitHub. While this open-source project is currently maintained by G-Research, there aren't enough core contributors to go around and your contribution will help us build better for all!
Note that these are guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.
I don't want to read this whole thing, I just have a question!
What should I know before I get started?
This project and everyone participating in it is governed by the SDC Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to conduct.sparkdc@gr-oss.io.
Note: Please don't file an issue to ask a question. You'll get faster results by using Github Discussions, the primary SDC discussion forum.
The SDC is an open source project that supports Spark for Python and Scala. When considering a contribution to SDC, you might be unsure where to start or how to report a bug. This document should help you with that.
We plan to document all significant decisions regarding project maintenance, support, and future features in Github Discussions under announcements. If you have a question around how we do things, and it is not documented there, please open a new topic on Github Discussions under questions and ask your question.
This section guides you through submitting a bug report for SDC. Following these guidelines helps core contributors and the community understand your report 📝, reproduce the behavior 💻 💻, and find related reports 🔎.
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.
-
Determine what type of bug it is — is it related to 📑documentation📑 or is it just a 🐞bug🐞 — and label it.
-
Provide details by explaining the problem and include additional details to help core contributors reproduce the problem. You can choose from presettemplates if applicable.
- Use a clear and descriptive title for the issue to identify the problem.
- Describe the exact steps which reproduce the problem in as much detail as possible. For example, start by explaining how you started SDC, that is, which command you typed in the terminal, or how you otherwise started SDC.
- 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.
- If the problem wasn't triggered by a specific action, describe what you were doing before the problem happened and share more information using the guidelines below.
- Provide more context by answering these questions:
- Can you reliably reproduce the issue? If not, provide details about how often the problem happens and under which conditions it normally happens.
- If the problem is related to working with files (e.g. opening and editing files), does the problem happen for all files and projects or only some? Does the problem happen only when working with local or remote files (e.g. on network drives), with files of a specific type (e.g. only Scala or Python files), with large files or files in a specific encoding? Is there anything else special about the files you are using?
This section guides you through submitting a feature request for SDC, including minor improvements to existing functionality. Following these guidelines helps core contributors and the community understand your suggestion 📝 and find related suggestions 🔎.
Before creating enhancement suggestions, please review the features and enhancements already in issues as you might learn that your feature request has already been suggested. When you are creating a feature request, please include as many details as possible.
- Use a clear and descriptive title for the issue to identify the suggestion.
- Provide a step-by-step description of the suggested feature/enhancement in as much detail as possible.
- Provide examples to demonstrate the feature/enhancement. Include copy/pasteable snippets which you use in those examples, as Markdown code blocks.
- Describe the current behavior and explain why the suggested behavior would be an improvement.
- If applicable, include screenshots or animated GIFs which help you demonstrate the steps or point out the part the suggestion is related to. You can use this tool to record GIFs on macOS and Windows, and this tool or this tool on Linux.
- Explain why this feature/enhancement would be useful to most SDC users.
- If possible, list some other applications where this feature/enhancement exists.
- Specify the name and version of the OS you're using.
If you would like to offer a contribution, please open a pull request following the instructions below. The process described here has several goals:
- Maintain the quality of the SDC
- Fix problems that are important to users
- Engage the community in working toward the best possible product
- Enable a sustainable system for SDC's core contributors to review contributions
Please follow these steps to have your contribution considered by the core contributors:
- Follow all instructions in the 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 core contributor 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 approved.
- Use the present tense ("Add feature" not "Added feature")
- Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
- Limit the first line to 72 characters or less
- Reference issues and pull requests liberally after the first line
- Label your issue if possible
This section lists the labels we use to help us track and manage issues and pull requests.
GitHub search makes it easy to use labels for finding groups of issues or pull requests you're interested in. The labels are loosely grouped by their purpose, but it's not required that every issue has a label from every group or that an issue can't have more than one label from the same group.
Please open an issue if you have suggestions for new labels.
| Label | Search | Description |
|---|---|---|
bug |
🔎 | Something isn't working |
dependencies |
🔎 | Upgrading or fixing dependencies |
documentation |
🔎 | Improvements or additions to documentation |
duplicate |
🔎 | This issue or pull request already exists |
enhancement |
🔎 | New feature or request |
github_actions |
🔎 | Pull requests that update Github actions code |
good first issue |
🔎 | Good for newcomers |
help-wanted |
🔎 | Extra attention is needed |
invalid |
🔎 | This doesn't seem right |
java |
🔎 | Pull requests that update Java code |
python |
🔎 | Pull requests that update Python code |
question |
🔎 | Further information is requested |
use_case |
🔎 | A specific use case or testimonial |
wontfix |
🔎 | This will not be worked on for now |