Contributing to Dragonfire¶
|sparkles:||First off all, thanks for taking the time to contribute! :sparkles:|
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.
Table Of Contents¶
Contributing to Dragonfire .. code-block:: guess
- [Table Of Contents](#table-of-contents)
- Code of Conduct
- Getting Started
- How Can I Contribute?
- Build the Debian package
- API Reference
I don’t want to read this whole thing I just have a question!!!¶
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.
Step 1: Set Up Git¶
Step 2: Fork The Repo¶
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.
Step 3: Create a local clone of your fork¶
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.
git clone, and then paste the URL you copied in Step 2. It will look like this, with your GitHub username instead of
YOUR-USERNAME: .. code-block:: guess
Press Enter. Your local clone will be created: .. code-block:: guess
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 that needs
git clone https://github.com/YOUR-USERNAME/Dragonfire.git cd Dragonfire/ chmod +x install.sh sudo ./install.sh --dev --pip
If you face with a problem while installing or using Dragonfire then please take a look at the Troubleshooting section for the cases that fitting to your situation. Our chat room on Gitter is also a viable option for support requests.
Missing Software Packages (Optional)¶
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 the commands like
INKSCAPE install the necessary software to your system. You can see the list of built-in commands here.
Choice for Code Editor¶
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 an 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.
Your First Code Contribution¶
Unsure where to begin contributing to Dragonfire? You can start by looking through these
- 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
- 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.
For working well disciplined, you need to know how to deal with git’s push and pull mechanisms.
Step 1: Go to the local clone of your fork¶
cd into the local clone of your fork. Wherever the folder of Dragonfire is:
Step 2: Pull the Latest Changes¶
Now make sure your repository is up to date first using:
git pull origin master
Step 3: Write Your Code¶
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 the tests and you did not break any existing feature of Dragonfire.
Step 4: Push To Your Fork¶
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.</sup>`
Step 5: Creating a Pull Request¶
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.
Git Commit Messages¶
- 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
: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
Build the Debian package¶
Install build dependencies:
sudo apt-get install debhelper python2.7-minimal python3 python3-all-dev python-setuptools python3-setuptools libglib2.0-dev libcairo2-dev libgtk2.0-dev
To building the Debian package simply run:
cd Dragonfire/ dpkg-buildpackage -us -uc
It will save the
.deb file into parent directory.
debian/ directory is the directory contains all the configuration files and pre/post-installation scripts related to Debian packaging.
API reference of Dragonfire hosted on Read the Docs and the build of documentation is automatically triggered by a webhook so you don’t have to really do anything about it.
If you want to build the documentation on your local machine for some reason then do the following:
cd docs/ sphinx-apidoc -f -o source/ ../dragonfire/ sphinx-build -b html source/ build/