Thank you for considering contributing to Kedro-Viz! We welcome contributions in the form of pull requests, issues or code reviews. You can add to code, or simply send us spelling and grammar fixes or extra tests. Contribute anything that you think improves the community for us all!
The following sections describe our vision and the contribution process.
The Kedro team pledges to foster and maintain a welcoming and friendly community in all of our spaces. All members of our community are expected to follow our Code of Conduct and we will do our best to enforce those principles and build a happy environment where everyone is treated with respect and dignity.
We use GitHub Issues to keep track of known bugs. We keep a close eye on them and try to make it clear when we have an internal fix in progress. Before reporting a new issue, please do your best to ensure your problem hasn't already been reported. If so, it's often better to just leave a comment on an existing issue, rather than create a new one. Old issues also can often include helpful tips and solutions to common problems.
If you are looking for help with your code, please consider posting a question on Stack Overflow. If you tag it kedro-viz, kedro and python, more people will see it and may be able to help. We are unable to provide individual support via email. In the interest of community engagement we also believe that help is much more valuable if it's shared publicly, so that more people can benefit from it.
If you're over on Stack Overflow and want to boost your points, take a look at the kedro-viz tag and see if you can help others out by sharing your knowledge. It's another great way to contribute.
If you have already checked the existing issues on GitHub and are still convinced that you have found odd or erroneous behaviour then please file a new issue. We have a template that helps you provide the necessary information we'll need in order to address your query.
If you have new ideas for Kedro-Viz functionality then please open a GitHub issue with the label Type: Enhancement. Please describe in your own words the feature you would like to see, why you need it, and how it should work.
If you're unsure where to begin contributing to Kedro-Viz, please start by looking through the good first issues and Request: Help Wanted on GitHub.
Typically, small contributions to Kedro-Viz are more preferable due to an easier review process, but we accept any new features if they prove to be essential for the functioning of the plugin or if we believe that they are used by most projects.
Working on your first pull request? You can learn how from these resources:
Note: We only accept contributions under the Apache 2.0 license and you should have permission to share the submitted code.
- Aim for cross-platform compatibility on Windows, macOS and Linux, and support recent versions of major browsers
- We use SemVer for versioning
- Our code is designed to be compatible with Python 3.6 onwards
- We use Anaconda as a preferred virtual environment
- We use PEP 8 conventions for all Python code
- We use Google docstrings for code comments
- We use PEP 484 type hints for all user-facing functions / class methods e.g.
def count_truthy(elements: List[Any]) -> int:
return sum(1 for elem in elements if elem)
- Keep UI elements fully keyboard accessible, and aim to support screen-readers where possible
- Maintain a high level of animation performance, and minimise page-load time
First clone this repo, then download and install dependencies:
npm installNow you're ready to begin development. Start the development server:
npm startThis will serve the app at localhost:4141, and watch files in /src for changes. It will also update the /lib directory, which contains a Babel-compiled copy of the source. This directory is exported to npm, and is used when importing as a React component into another application. It is updated automatically when you save in case you need to test/debug it locally (e.g. with npm link). You can also update it manually, by running
npm run libKedro-Viz uses a unique identifier to determine the data source from one of several available sources. You can configure this by appending a query string to the URL, e.g. http://localhost:4141/?data=random. Alternatively, you can set it with an environment variable when starting up the dev server:
DATA=random npm startThese are the supported dataset identifiers:
| Identifier | Data source |
|---|---|
json (default) |
/public/api/main |
random |
Randomly-generated data |
demo |
/src/utils/data/demo.mock.js |
animals |
/src/utils/data/animals.mock.json |
By default in production, the app asynchronously loads JSON from the /api/main endpoint. You can replicate this in development by placing a JSON dataset in /public/api/main, using main as the name of the file, without an extension. Note that operating systems often add hidden file extensions, so you might need to use a CLI to confirm the filename.
Alternatively, you can synchronously load one of the mock datasets in /src/utils/data. The 'animals' dataset is mainly used as mock data for unit testing, while the 'demo' dataset is used on the public demo.
Finally, you can use pseudo-random data, which is procedurally-generated on page load, and is often useful for local development. Random data can be seeded with a hash string, which will allow you to replicate a generated layout. You can supply a seed with a seed query string in the URL, e.g. http://localhost:4141/?data=random&seed=oM4xauN4Whyse. If you do not supply a seed, the app will generate a new pseudo-random one every time, and will output it to the browser console in case you wish to reuse it.
We use a branching model that helps us keep track of branches in a logical, consistent way. All branches should have the hyphen-separated convention of: <type-of-change>/<short-description-of-change> e.g. feature/awesome-new-feature
| Types of changes | Description |
|---|---|
docs |
Changes to the documentation of the plugin |
feature |
Non-breaking change which adds functionality |
fix |
Non-breaking change which fixes an issue |
tests |
Changes to project unit (tests/) and / or integration (features/) tests |
- Fork the project
- Develop your contribution in a new branch and open a PR against the
mainbranch - Make sure the CI builds are green (have a look at the section Running checks locally below)
- Update the PR according to the reviewer's comments
This app uses Jest and Enzyme to run JavaScript tests, which you can invoke as follows:
npm testYou can also inspect and debug tests:
npm run test:debugAnd check test coverage:
npm run test:coverageSee the Create-React-App docs for further information on JS testing.
You can simulate how the published package will behave when imported into another JavaScript application by running
npm run lib-testThis script uses npm pack to package Kedro-Viz as a tarball, then copies it to a boilerplate React app in /tools/test-lib/react-app and installs it. Next, the script runs a simple server at http://localhost:1337, which will open in the browser so that you can check that everything is working as it should.
You can also run automated tests on this demo app by copying and installing the tarball package, navigating to the test directory and running Jest:
npm run lib-test:setup
cd tools/test-lib/react-app
npm testTo run E2E tests you need to install the test requirements which includes behave, do this using the following command:
pip install -r test_requirements.txtAll checks run by our CI / CD pipeline can be run locally on your computer.
make lintmake pytestmake e2e-testsThe version number for Kedro-Viz is defined in three places, which all need to be maintained at the same version number:
package.jsonpackage-lock.jsonpackage/kedro_viz/__init__.py
The Makefile contains a version target which accepts the VERSION argument
or environmental variable, which will update all the files at the same time. To update the version and prepare a new release, first check that the release notes are up to date, then run the following command:
make version VERSION=1.0.5