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 Discord community.
Ways to contribute
- Stars on GitHub: If you're 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're 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 Discord.
- 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 - every contribution will be welcomed with great pleasure!
Make sure you have
python3.9 installed on your system.
You'll also need to have poetry installed.
After forking and cloning the repository, run:
# If you intend to work on coco related things, run this instead:
poetry install --extras "coco"
You might need to install
xcode-select if you are on Mac or
C++ build tools if you are on Windows.
After the installation is done, you can activate the created virtual environment with:
You're all set up, now you should be able to run your locally installed
Make sure you are always running
encord-active from the activated virtual environment to not conflict with a globally installed version.
Running the frontend
Our frontend is build with React. To start it in development mode, run:
Running the frontend locally is only required if you intend to work on our React frontend components
cd 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
Running the documentation
Our documentation is built with Docusaurus. To start it in development mode, run:
cd docs && npm i && npm start
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>
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
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
- Github CLI
Firstly, you need to visit the Encord Active repository and fork into your own account. The
fork button is at the right top corner of the web page alongside with buttons such as
star (highly appreciated if you click this one as well 🌟).
Now, you can clone your own forked repository into your local environment.
git clone https://github.com/<YOUR-USERNAME>/encord-active.git
If you have Github CLI installed this 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.
- Github CLI
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
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)
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.
- Github CLI
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
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.
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>
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
encord-team/encord-active. After creating this pull request, you should be able to see it here.
If you are using 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.