Development#

You can install mtools in development mode, which does not move it into the Python site-packages directory but keeps it in your local development directory instead. It still installs the necessary hooks so you can use it like normal, both from Python and the command line. In addition, you can modify the files directly in your local directory and test the changes right away.

Using a development branch#

Remove any existing mtools installation:
```
sudo pip3 uninstall mtools
```
Fork the mtools repository to your own GitHub account.
Clone your mtools fork to your development environment. This step creates an mtools directory in the current directory, so you may want to switch to an appropriate directory first (for example ~/code/):
```
cd ~/code
git clone https://github.com/<username>/mtools.git
```
Change into the mtools directory and check out the desired branch. All development should be based off the develop branch:
```
cd mtools
git checkout develop
```
Install the mtools scripts in development mode using either:
- pip3 (recommended as a convenience for installing additional dependencies):
```
sudo pip3 install -e '/path/to/cloned/repo[all]'
```
- setup.py
```
sudo python3 setup.py develop
```
Test the installation by confirming that the scripts tab-complete from any directory:
```
mlogf<tab>
```
This should auto-complete to mlogfilter. Also confirm the current version, which should end in -dev0 for the develop branch:
```
mlogfilter --version
```

Using the stable branch#

To use the latest stable release of mtools, check out the master branch:
```
git checkout master
```
Confirm your current version with the --version parameter:
```
mloginfo --version
```

Making pull requests#

mtools uses a simplified version of the git branching model by @nvie.

Important

The master branch should only ever contain versioned releases. Do not send pull requests against the master branch.

Development happens on the develop branch.

Fork the main repository into your own GitHub account.

Clone a copy to your local machine:

git clone https://github.com/<username>/mtools

Add the upstream repository to pull in the latest changes:

cd mtools
git remote add upstream https://github.com/rueckstiess/mtools
git fetch upstream

Check out and track your remote develop branch with a local branch:
```
git checkout -b develop origin/develop
```
If you want to work on a bug or feature implementation, pull in the latest changes from upstream:
```
git checkout develop
git pull upstream develop
```
Create a feature or bug fix branch that forks off the local develop branch. The branch should named after the GitHub issue number you are working on. If there isn’t a GitHub issue yet, please create one.
```
git checkout -b issue-12345 develop
```
Make your changes to the code. Commit as often as you like. Please use meaningful, descriptive commit messages and avoid asdf or changed stuff descriptions.
Add or update tests to confirm your changes are working as expected. See Testing for more information.
When you’re happy with your changes, push your feature branch to GitHub:
```
git push origin issue-12345
```
Raise a pull request against the upstream develop branch using the GitHub interface.
After the code is merged into the develop branch, you can pull the change from the upstream develop branch and delete your local feature or bug fix branch:
```
git checkout develop
git pull upstream develop
git push origin --delete issue-12345
git branch -d issue-12345
```