✨ First off all, thanks for taking the time to contribute! ✨
The following is a set of guidelines for contributing to Dragonfire an open source virtual assistant project, which is hosted in the Dragon Computer Organization on GitHub. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.
This project and everyone participating in it is governed by the Dragonfire's Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to mert.yildiran@bil.omu.edu.tr.
Note: Please don't file an issue to ask a question. You'll get faster results by using the resources below.
We have an official chat room on Gitter where the community chimes in with helpful advice if you have questions.
| Operating systems | Linux |
| Python versions | CPython 2.7. Only 64 bit. |
| Distros | KDE neon, elementary OS, Ubuntu |
| Package managers | APT, pip |
| Languages | English |
| System requirements | Minimally 1 Core, 2GB free RAM |
Supported Distributions: KDE neon, elementary OS and Ubuntu. All modern releases (Ubuntu 12.04 LTS and above) of these distributions are fully supported. Any other Ubuntu based distributions are partially supported.
If you haven't yet, you should first set up Git. Don't forget to set up authentication to GitHub from Git as well.
Forking a repository is a simple two-step process:
- On GitHub, navigate to the DragonComputer/Dragonfire repository.
- In the top-right corner of the page, click Fork.
That's it! Now, you have a fork of the original Dragonfire repository under your account.
Right now, you have a fork of the Dragonfire repository, but you don't have the files in that repository on your computer. Let's create a clone of your fork locally on your computer:
- On GitHub, navigate to your fork of the Dragonfire repository.
- Under the repository name, click Clone or download.
- Copy the given clone URL in the Clone with HTTPs section.
- Open Terminal
- Type
git clone, and then paste the URL you copied in Step 2. It will look like this, with your GitHub username instead ofYOUR-USERNAME:
git clone https://github.com/YOUR-USERNAME/Dragonfire.git
- Press Enter. Your local clone will be created:
git clone https://github.com/YOUR-USERNAME/Dragonfire.git
Cloning into 'Dragonfire'...
remote: Counting objects: 1076, done.
remote: Compressing objects: 100% (6/6), done.
remote: Total 1076 (delta 4), reused 9 (delta 4), pack-reused 1066
Receiving objects: 100% (1076/1076), 13.85 MiB | 1.62 MiB/s, done.
Resolving deltas: 100% (597/597), done.
Checking connectivity... done.
You need to install Dragonfire with sudo rights, even if you are installing editable/development mode because there is a post-installation script needs sudo rights.
git clone https://github.com/YOUR-USERNAME/Dragonfire.git
cd Dragonfire/
sudo pip install -e .alternatively you can install it with:
sudo pip install -Uve .
which means: -U (upgrade), -v (verbose), -e (editable/development mode)
Post-installation script consists of the these lines. It's important to know it for troubleshooting installation problems.
Try to experience every command listed in README.md. Please watch this playlist if you do not understand how to use Dragonfire.
If you face with a problem while installing or using Dragonfire then please take a look to the Troubleshooting section for cases that fitting to you situation. Our chat room on Gitter is also a viable option for support requests.
There could be missing software packages on your system like blender, gimp, inkscape, kdenlive, etc. So Dragonfire will be unable to open them. If you want to use commands like PHOTO EDITOR, INKSCAPE install the necessary software on your system. You can see the list of built-in commands here.
We use Atom Editor with tabs(four whitespaces) without auto-indentation. Indentation mistakes can be troublesome in Python, please don't send files with messed up indentations.
If you are wondering about the package structure and distribution then please take a look to the official Packaging and Distributing Projects tutorial of Python.
If you think you found a bug in Dragonfire then frist please check the all cases listed in Troubleshooting section. If you still think that's a bug then please file an issue immediately. Don't forget to mention that it's a bug or something going on very wrong.
Note: If you find a Closed issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one.
If you have a enhancement idea or you are not happy with an ugly piece of code then please file an issue and mention that it's an enhancement proposal.
Look at the cards pinned to To Do columns inside open projects to find something suitable for you. If you are willing to take a card/task from there then contact with project maintainers via Gitter chat room so they will assign that task to you.
Unsure where to begin contributing to Dragonfire? You can start by looking through these beginner and help-wanted issues:
- Beginner issues which should only require a few lines of code, and a test or two.
- Help wanted issues which should be a bit more involved than
beginnerissues. - Missing dependency issues which should be mostly platform/distro related issues.
- Enhancement proposals which should be improvements ideas or alteration proposals on code.
- Bugs which should be issued with proof of existence and expected to be hard to fix.
Now you must have decided what to do. Before starting to write some code, take a quick look to PEP 8 - because 👇
For working well disciplined, you need to know how to deal with git's push and pull mechanisms.
Now cd into the local clone of your fork. Wherever the folder of Dragonfire is:
cd Dragonfire/
Now make sure your repository is up to date first using:
git pull origin master
At this step you are free to make any changes inside the local clone of your fork. Make sure that your changes serve to single well defined goal which will be your commit message. DO NOT try to achieve multiple (and unrelated) tasks with a single commit.
Before proceeding to Step 4, make sure that you have done all tests and you did not break any existing feature of Dragonfire.
When you are done, you must push your changes from the local clone to your fork with:
git add -A
git commit -m "Change this functionality from here to there"
git push -u origin master
Replace the message in git commit -m "Change this functionality from here to there" line with your actual message.
Now follow this tutorial to create a pull request. You will create your pull request via this page.
Once you have successfully created the pull request, wait for a response from the project maintainers. If your patch is OK then we will merge it within approximately 24 hours.
- Use the present tense ("Add feature" not "Added feature")
- Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
- Limit the first line to 72 characters or less
- Reference issues and pull requests liberally after the first line
- Consider starting the commit message with an applicable emoji:
- 🎨
:art:when improving the format/structure of the code - 🚀
:rocket:when improving performance - 🤖
:robot:when improving the AI - 📝
:memo:when writing docs - 🐧
:penguin:when fixing something related to Linux - 🍎
:apple:when fixing something related to macOS - 🐛
:bug:when fixing a bug - 💡
:bulb:new idea - 🚧
:construction:work in progress - ➕
:heavy_plus_sign:when adding feature - ➖
:heavy_minus_sign:when removing feature - 🔈
:speaker:when adding logging - 🔇
:mute:when reducing logging - 🔥
:fire:when removing code or files - ✅
:white_check_mark:when adding tests - 🔒
:lock:when dealing with security - ⬆️
:arrow_up:when upgrading dependencies - ⬇️
:arrow_down:when downgrading dependencies - 👕
:shirt:when removing linter warnings
- 🎨
All Python must adhere to PEP 8.
If there is no sound coming from your speakers when you see Dragonfire: GOOD MORNING SIR on your terminal or To activate say 'Dragonfire!' or 'Wake Up!' notification after you run Dragonfire with dragonfire command then there are two possibilities causing this problem:
- Dragonfire's audio output (ALSA plug-in [aplay]: ALSA Playback) could be mapped to wrong audio device:
you can fix this either by changing it to correct device using the audio settings of your operating system or you can choose to use Phonon sudo apt-get install phonon to configure your device priority:
- The problem could be related to missing
festivalpackage on your system. It should normally be installed on post-installation automatically but try to install it one more time with:
sudo apt-get update
sudo apt-get install festival
If festival is missing in your repositories then download it and try to install it with sudo dpkg -i festival_2.4-release-2_amd64.deb.
- First of all, Dragonfire's speech recognition ability needs an Internet connection so make sure your machine is connected to the Internet.
- If Internet connection is not the issue then check the output of
ps -aux | grep juliuswhile Dragonfire is running. You must see an output like this:
mertyil+ 2402 4.0 0.3 443656 27780 pts/2 Sl+ 04:48 0:00 julius -input mic -C /home/mertyildiran/Documents/Dragonfire/dragonfire/julian.jconf
- If you cannot see such an output then that means speech recognition is not even started so that means padsp and/or julius is missing on your system.
- If you see such an output then most probably Dragonfire's audio input (ALSA plug-in [julius]: ALSA Capture) is mapped to wrong audio device:
you can fix this either by changing it to correct device using the audio settings of your operating system or you can choose to use Phonon sudo apt-get install phonon to configure your device priority:
Dragonfire starts on sleeping mode to do not disturb your acoustic environment. You need to active her by saying DRAGONFIRE or HEY or WAKE UP to your microphone.
Then you need to deactivate her by saying GO TO SLEEP.
Then you need to silence her by saying ENOUGH OR SHUT UP.
By saying GOODBYE or BYE BYE or SEE YOU LATER.
Dragonfire analyzes your name that registered on the operating system to determine your gender. Sometimes she makes mistakes (mostly if your name is not an English name) and call you by your opposite gender. To fix this you can say MY TITLE IS SIR or I'M A MAN or I'M A BOY.
Dragonfire analyzes your name that registered on the operating system to determine your gender. Sometimes she makes mistakes (mostly if your name is not an English name) and call you by your opposite gender. To fix this you can say MY TITLE IS LADY or I'M A LADY or I'M A WOMAN or I'M A GIRL.
Sure, there is a command for that. You can usee CALL ME * command to manipulate her form of address for you to anything you want. For example: CALL ME MASTER or CALL ME MY LORD or CALL ME MY FRIEND etc.
Probably you don't have any of the supported file manager software packages: dolphin, pantheon-files, nautilus
Check the existence of sensible-browser command. It's a command that points out to your default web browser.
Probably you don't have GIMP installed on your system: sudo apt-get install gimp
Probably you don't have Inkscape installed on your system: sudo apt-get install inkscape
Probably you don't have any of the supported video editor software packages: openshot, lightworks, kdenlive
This script will try to install dependencies for you. Run these commands, respectively:
wget https://raw.githubusercontent.com/DragonComputer/Dragonfire/master/install.sh
chmod +x install.sh
sudo ./install.sh
Dragonfire's learning is far from perfect so by the time, the conversations filled with incorrect information can lead her to wrong answers like THE SUN IS HOT AND COLD. To fix this kind of situations you can always wipe out her memories about the subject by calling: FORGET ABOUT THE SUN
Learning feature has a priority so if in the past, you said something like ALBERT EINSTEIN IS A PHYSICIST then it will block your way when you asked anything about Albert Einstein. To fix this you should say: FORGET ABOUT ALBERT EINSTEIN
🏁 If none of the cases listed above are fitting to your situation then always consider to file an issue or visit our chat room on Gitter.