Note: Meltano uses >= python3.6
We welcome contributions, idea submissions, and improvements. In fact we may already have open issues labeled Accepting Merge Requests if you don't know where to start. Please see the contribution guidelines below for source code related contributions:
# Clone the Meltano repo git clone email@example.com:meltano/meltano.git # Change directory into the Meltano project cd meltano # Optional, but it's best to have the latest pip pip install --upgrade pip # Optional, but it's best to have the latest setuptools pip install --upgrade setuptools # Optional, but it's recommended to create a virtual environment # in order to minimize side effects from unknown environment variable python -m venv venv # Activate your virtual environment source ./venv/bin/activate # Install all the dependencies pip install -r requirements.txt # Install dev dependencies with the edit flag on to detect changes # Note: you may have to escape the `.[dev]` argument on some shells, like zsh pip install -e .[dev] # Run scripts to create remaining required files make bundle
Meltano is now installed and available at
Head out to the tutorials to create your first project.
For all changes that do not involve working on Meltano UI itself, run the following command:
# Starts both Meltano API and a production build of Meltano UI meltano ui
In the event you are contributing to Meltano UI and want to work with all of the frontend tooling (i.e., hot module reloading, etc.), you will need to run the following commands:
# Starts the Meltano API and a production build of Meltano UI that you can ignore meltano ui # Open a new terminal tab and go to your meltano directory. Then change directory to analyze cd src/analyze # Install dependencies npm install # or yarn # Start local development environment npm run dev # or yarn dev
Follow the merge request and changelog portions of this contribution section for text-based documentation contributions.
When adding supporting visuals to documentation, adhere to:
src/docs/.vuepress/public/screenshots/with a descriptive name
When testing your contributions you may need to ensure that your various
__pycache__ directories are removed. This helps ensure that you are running the code you expect to be running.
The below visual hierarchy defines the back to front depth sorting of UI elements. Use it as a mental model to inform your UI decisions.
There are three fundamental markup groups in the codebase. All three are technically VueJS single-file components but each have an intended use:
Here is a technical breakdown:
<router-view-layout>as root with only two children:
<div class="container view-header">
<div class="container view-body">
<section>as root (naturally assumes a parent of
<div class="container view-body">) with one type of child:
<div class="columns">each with their needed
Searching for something to work on?
Start off by looking at our ~"Accepting Merge Request" label.
Keep in mind that this is only a suggestion: all improvements are welcome.
Meltano uses an approval workflow for all merge requests.
A contributor can ask for a review on any merge request, without this merge request being done and/or ready to merge.
Asking for a review is asking for feedback on the implementation, not approval of the merge request. It is also the perfect time to familiarize yourself with the code base. If you don’t understand why a certain code path would solve a particular problem, that should be sent as feedback: it most probably means the code is cryptic/complex or that the problem is bigger than anticipated.
Merge conflicts, failing tests and/or missing checkboxes should not be used as ground for sending back a merge request without feedback, unless specified by the reviewer.
Meltano uses changelog-cli to populate the CHANGELOG.md
changelog (new|change|fix|breaks) MESSAGE to describe your current work in progress.
$ changelog new "add an amazing feature" $ git add CHANGELOG.md
Make sure to add CHANGELOG entries to your merge requests.
Meltano uses semver as its version number scheme.
Ensure you have the latest
master branch locally before continuing.
# get latest master branch $ git fetch origin
Meltano uses tags to create its artifacts. Pushing a new tag to the repository will publish it as docker images and a PyPI package.
# activate your virtualenv $ source ./venv/bin/activate # pip install all the development dependencies $ pip install .[dev]
# if you've released before, you may need to delete the last local release branch you created $ git branch -D release-next # create and checkout release-next branch that's based off master branch $ git checkout -b release-next origin/master # view changelog (verify changes made match changes logged) $ changelog view # after changelog validation, build the release $ make release # after building the release, check the version we just bumped to: e.g. `0.22.0` => `0.23.0`. # occasionally the version bump can go to a version you don't expect. $ changelog view # validate that the tag auto increments based on semver $ git push --tags # update meltano repo with release-next branch $ git push origin release-next
masterand make sure to check
delete the source branch when the changes are merged.
We should be good citizen about these, and use the default workflow to contribute. Most of these are on GitHub so:
We will maintain a curated list of taps/targets that are expected to work out of the box with Meltano.
Meltano should help the end-user find components via a
$ meltano discover extract tap-demo==... tap-zendesk==1.3.0 tap-marketo==... ... $ meltano discover load target-demo==... target-snowflake==git+https://firstname.lastname@example.org target-postgres==...
Tmuxinator is a way for you to efficiently manage multiple services when starting up Meltano.
In order to run applications, you need to run multiple sessions and have to do a lot of repetitive tasks (like sourcing your virtual environments). So we have created a way for you to start and track everything in its appropriate panes with a single command.
It's a game changer for development and it's worth the effort!
This config uses
$MELTANO_VENV to source the virtual environment from. Set it to the correct directory before running tmuxinator.
.venvin line 2 refers to your virtual environment directory in Step #1.
$ cd path/to/meltano $ MELTANO_VENV=.venv tmuxinator local