Contributing Guidelines
June 24, 2025 ยท View on GitHub
We appreciate your contribution to this amazing project! Any form of engagement is welcome, including but not limiting to
- feature request
- documentation wording
- bug report
- roadmap suggestion
- ...and so on!
Please refer to the community contributing section for more details.
Development and codebase contribution
Before delving into the details to come up with your first PR, please familiarise yourself with the project structure of Instill Core.
Setup
Requirements
- Make:
- macOS:
$ xcode-select --install - Linux: https://www.gnu.org
- macOS:
- Python:
$ conda create -n sdk python=3.Xhttps://docs.conda.io/projects/miniconda/en/latest/
- Poetry: https://python-poetry.org
To confirm these system dependencies are configured correctly:
Installation
Fetch git submodules:
make get-proto
Fetch and generate json schema files and dataclass:
make update-specs
# `instill/resources/schema/airbyte/OAuth2.py` will be generated with an error, need to manually remove the `OAuth2.` in `OAuth2.AuthType.OAuth2_0`
Important
Create a .venv folder if you are using conda
This will be fixed soon, but currently if you are installing the development dependencies inside a conda env,
you will need to create a .venv folder in your project root to prevent errors
Install project dependencies into a virtual environment:
make install
Development Tasks
Manual
Run the tests:
make test
Run static analysis:
make check
Build the documentation:
make docs
Automatic
Keep all of the above tasks running on change:
make dev
In order to have OS X notifications,
brew install terminal-notifier.
Continuous Integration
The CI server will report overall build status:
make all
Release Tasks
Release to PyPI:
make upload
Sending PRs
Please take these general guidelines into consideration when you are sending a PR:
- Fork the Repository: Begin by forking the repository to your GitHub account.
- Create a New Branch: Create a new branch to house your work. Use a clear and descriptive name, like
<your-github-username>/<what-your-pr-about>. - Make and Commit Changes: Implement your changes and commit them. We encourage you to follow these best practices for commits to ensure an efficient review process:
- Adhere to the conventional commits guidelines for meaningful commit messages.
- Follow the 7 rules of commit messages for well-structured and informative commits.
- Rearrange commits to squash trivial changes together, if possible. Utilize git rebase for this purpose.
- Push to Your Branch: Push your branch to your GitHub repository:
git push origin feat/<your-feature-name>. - Open a Pull Request: Initiate a pull request to our repository. Our team will review your changes and collaborate with you on any necessary refinements.
When you are ready to send a PR, we recommend you to first open a draft one. This will trigger a bunch of integration-test workflows running a thorough test suite on multiple platforms. After the tests are done and passed, you can now mark the PR open to notify the codebase owners to review. We appreciate your endeavour to pass the integration test for your PR to make sure the sanity with respect to the entire scope of Instill Core.
Last words
Your contributions make a difference. Let's build something amazing together!