Contributing
We follow a code of conduct when participating in the community. Please read it before you make any contributions.
- If you plan to work on an issue, mention so in the issue page before you start working on it.
- If you plan to work on a new feature, create an issue and discuss it with other community members/maintainers.
- Ask for help in our Slack community.
Ways to contribute
- Stars on GitHub: If you are an Encord Active user and enjoy using our platform, don't forget to star it on GitHub! 🌟
- Improve documentation: Good documentation is imperative to the success of any project. You can make our documents the best they need to be by improving their quality or adding new ones.
- Give feedback: We are always looking for ways to make Encord Active better, please share how you use Encord Active, what features are missing and what is done good via Slack.
- Share refine: Help us reach people. Share Encord Active repository with everyone who can be interested.
- Contribute to codebase: Your help is needed to make this project the best it can be! You could develop new features or fix existing issues - all contributions are welcome!
Environment setup
Make sure you have python3.9
installed on your system.
To install the correct version of python you can use pyenv, brew (mac only) or simply download it.
You'll also need to have poetry installed.
After forking and cloning the repository, run:
poetry install
# If you intend to work on coco related things, run this instead:
poetry install --extras "coco"
Note
You might need to install
xcode-select
if you are on Mac orC++ build tools
if you are on Windows.
After the installation is done, you can activate the created virtual environment with:
poetry shell
Now you should be able to run your locally installed encord-active
.
Note
Make sure you are always running
encord-active
from the activated virtual environment to not conflict with a globally installed version.
Running the frontend
Note
Running the frontend locally is only required if you intend to work on our React frontend components.
Our frontend is build with React. To start it in development mode, run:
cd "frontend_components/encord_active_components/frontend" && npm i && npm start
In order to point encord-active
to your locally running frontend, you'll need to change the FRONTEND
environment variable in the .env
file. Make sure you point it to the correct port, by default it should be running on http://localhost:5173/
Commit convention
Commit messages are essential to make changes clear and concise. We use conventional commits to keep our commit messages consistent and easy to understand.
<type>(optional scope): <description>
Examples:
feat: allow provided config object to extend other configs
fix: array parsing issue when multiple spaces were contained in string
docs: correct spelling of CHANGELOG
Contribution guide
You need to follow these steps below to make contribution to the main repository via pull request. You can learn about the details of pull request here.
1. Fork the official repository
If you are using Git, you can visit the Encord Active repository and find the Fork button at the right top corner of the web page, along with other buttons such as Watch and Star (highly appreciated if you click this one as well 🌟). Simply click the Fork button to create a copy of the repository under your own account.
Now, you can clone your own forked repository into your local environment.
git clone https://github.com/<YOUR-USERNAME>/encord-active.git
Otherwise, if you have the GitHub CLI installed, the following command will create a fork. If you haven't, consider installing it.
gh repo fork encord-team/encord-active
2. Configure Git
You need to set the official repository as your upstream so that you can synchronize with the latest updates in the official repository. You can learn about syncing forks here.
With Git, it's as simple as running the following commands:
cd encord-active
git remote add upstream https://github.com/encord-team/encord-active.git
If you use the GitHub CLI, this step is done automatically 🪄
You can use the following command to verify that the remote is set. You should see both origin
and upstream
in the output.
git remote -v
> origin https://github.com/<YOUR-USERNAME>/encord-active.git (fetch)
> origin https://github.com/<YOUR-USERNAME>/encord-active.git (push)
> upstream https://github.com/encord-team/encord-active.git (fetch)
> upstream https://github.com/encord-team/encord-active.git (push)
3. Synchronize
Before you make changes to the codebase, it is always good to fetch the latest updates in the official repository. In order to do so, you can use the commands below.
Git
git fetch upstream
git checkout main
git merge upstream/main
git push origin main
Otherwise, you can click the fetch upstream
button on the GitHub webpage of the main branch of your forked repository. Then, use these commands to sync.
git checkout main
git fetch main
GitHub CLI
To sync your remote fork:
gh repo sync <YOUR-USERNAME>/encord-active
And then to sync your local clone:
gh repo sync
4. Pull request issue
In order to not waste your time implementing a change that has already been declined, or is generally not needed, start by opening an issue describing the problem you would like to solve. Make sure you use appropriate title and description and be as descriptive as possible.
Generally, your code change should be only targeting one problem in order to make the review process as simple as possible.
5. Make changes
You should not make changes to the main
branch of your forked repository as this might make upstream synchronization difficult. You can create a new branch with the appropriate name. Generally, branch names should start with a conventional commit type, e.g. fix/
/ docs/
/ feat/
followed by the scope.
git checkout -b <NEW-BRANCH-NAME>
It is finally time to implement your change!
You can commit and push the changes to your local repository. The changes should be kept logical, modular and atomic.
git add -A
git commit -m "<COMMIT-TYPE>: <COMMIT-MESSAGE>"
git push -u origin <NEW-BRANCH-NAME>
Tip
If you are making changes to the frontend, you can run
encord-active config set dev true
to enable file watchers. This will make the UI detect code changes and suggest to (auto) refresh the page.
7. Open a pull request
You can now create a pull request on the GitHub webpage of your repository. The source branch is <NEW-BRANCH-NAME>
of your repository and the target branch should be main
of encord-team/encord-active
. After creating this pull request, you should be able to see it here.
If you are using the GitHub CLI you can run:
gh pr create --web
Fill out the title and body appropriately trying to be as clear as possible. And again, make sure to follow the conventional commit guidelines for your title.
Do write a clear description of your pull request and link the pull request to your target issue. This will automatically close the issue when the pull request is approved.
In case of code conflict, you should rebase your branch and resolve the conflicts manually.
Updated 5 days ago