Contributing to an open source project is a great way to build skills, make connections, and gain experience. Here are the first steps to becoming a contributor:
- You can connect with us on our Slack Channel - let us know you wish to contribute, and we'll get you started.
- Check out our good first issues.
- Try out VDK and tell us what you think by scheduling an informal 30-minute call with us.
- Start with our documentation and enhance it.
- Read a simple step-by-step guide by GitHub.
We welcome many different types of contributions, including:
- Adding new features and proposals
- Creating and updating documentation
- Writing design specifications
- Creating visual graphics
- Identifying and fixing bugs
- Triaging issues
- Answering questions and providing feedback
- Helping onboard new contributors
- Creating content - blogs, videos, etc.
VDK follows the Code of Conduct, adapted from the Contributor Covenant. Please read the Code of Conduct guide to familiarize yourself with the expectations and responsibilities of the community.
If you wish to contribute code, you must sign the contributor license agreement (CLA). For any questions about the CLA process, please refer to our FAQ page.
Our repository is organized as a monorepo, meaning it houses multiple projects and plugins within the same repository.
You can find each individual project and plugin located in their respective directories. The design of our monorepo allows for each project and plugin to be developed independently.
What this means for your workflow is that when you want to work on a specific project or plugin, you only need to load that particular one into your IDE, rather than the entire monorepo. This should make it easier to focus on your specific task without getting lost in the entire codebase.
Familiarize with Versatile Data Kit Design Principles. We want to prioritize user-centered development, seamless user experience, and data-centric interfaces.
Familiarize with Versatile Data Kit Architecture
See Versatile Data Kit Coding Standard.
All contributors follow GitHub’s pull request (PR) workflow to submit changes. Before merging, all pull requests require two approvals.
Our branches follow the naming convention: person/<username>/<feature-name>
VDK follows semantic versioning standards as part of https://semver.org/.
Given a version number MAJOR.MINOR.PATCH, increment the:
- MAJOR version when you make incompatible API changes
- MINOR version when you add functionality in a backward-compatible manner
- PATCH version when you make backwards-compatible bug fixes
Here you can see what licenses are dependencies of Versatile Data Kit: Dependencies Licencing.
Review the list of existing issues to see if the bug has already been reported.
To report a bug, create a GitHub issue. Include steps to replicate the bug in the issue description.
If you believe you have found a security bug, reach out to us first using any method in the Contact Us section and create a GitHub issue.
Before proposing a feature or change, consider the impact of this change. Does it only serve your needs, or does it serve the broader community's needs?
For substantial features or changes, submitting your design is valuable.
To submit a change:
- Create a PR in Github.
- Follow the VDK Enhancement Proposal (VEP) template.
- Add your proposal as markdown in the /specs directory.
Reviews, feedback, and approvals are documented in the PR.
Reach out to the community through Slack or e-mail in the Contact Us section to discuss your idea. We are happy to help.
A typical development workflow has the following process:
- Create a topic branch from where you want to base your work, naming your branch according to our naming convention. For example,
person/<github-username>/<feature-name>. - Make commits in logical units.
- Use clear commit titles and commit descriptions.
- Push your changes to the topic branch in your fork.
- Create a pull request from the commit.
We follow the GitHub workflow. See GitHub flow for more information.
Note: Use forks only for examples and documentation contributions. Currently, we accept contributions from forks only for examples and documentation changes until PR 854 is fixed. Until then, please request write privileges and create a branch in the main repository.
There is no global IDE and testing setup because each plugin and project has its own development and setup guide. You can find these in the CONTRIBUTING.md for each project.
Follow the guides on how to setup IDE, build, test, run, and release - for vdk-core and vdk-control-cli
Here you can find a guide to Setting up GPG key for signing commits
Follow the guide on GitLab CI/CD
If this is your first PR, take a look at this video series to get you started: How to Contribute to an Open Source Project on GitHub.
Take a look at our list of good first issues. These issues are a great place to start.
If you see an issue that you would like to work on, leave a comment in the issue to let people know you are interested.
Before submitting your first PR, please review our general guidelines in How to prepare a new PR.
Before submitting your pull request, review the following:
- Check if your code changes pass code linting checks and unit tests.
- Ensure your commit messages are descriptive. Be sure to include any related GitHub issue references in the commit message. See Basic writing and formatting syntax for guidelines on syntax formatting.
- Check the commit and commit messages to ensure they are free from spelling and grammar errors.
- Use clear commit titles and commit descriptions for generating changelog release notes.
- All changes must be submitted to the main branch using pull requests.
- Any change must go on a feature branch or on a fork.
- Pipeline must pass before merging.
- Code commits must be broken down into small self-contained units.
- Commit messages must follow the template in git-commit-template.txt. See How to Write a Git Commit Message as a guideline to writing commit messages.
- The change must abide by the Versatile Data Kit Coding Standard.
- Each change is subject to two code reviews and approvals before it is merged.
We prefer to maintain a straight branch history by rebasing before merging. Fast-forward merges should not create merge conflicts.
To document your changes, follow the Documentation Guide
Ready to contribute? Look at the open issues list or create an issue for a suggested change.
You can reach out to us using any of the following:
- Connect on Slack by:
- Joining the CNCF Slack workspace.
- Joining the #versatile-data-kit channel.
- Follow us on Twitter.
- Join our development mailing list, used by developers and maintainers of VDK.