Skip to content

Latest commit

 

History

History
291 lines (200 loc) · 15.2 KB

CONTRIBUTING.md

File metadata and controls

291 lines (200 loc) · 15.2 KB
Raw

Contributing to Dragonfire

✨ 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.

Table Of Contents

Code of Conduct

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.

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.

Getting Started
Operating systems Linux
Python versions Python 3.x (64-bit)
Distros KDE neon, elementary OS, Ubuntu
Package managers APT, pip
Languages English
System requirements a CUDA supported GPU, 2GB of 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.

Fork The Repo

Step 1: Set Up Git

If you haven't yet, you should first set up Git. Don't forget to set up authentication to GitHub from Git as well.

Step 2: Fork The Repo

Forking a repository is a simple two-step process:

  1. On GitHub, navigate to the DragonComputer/Dragonfire repository.
  2. 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:

  1. On GitHub, navigate to your fork of the Dragonfire repository.
  2. Under the repository name, click Clone or download.
  3. Copy the given clone URL in the Clone with HTTPs section.
  4. Open Terminal
  5. Type 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:
git clone https://github.com/YOUR-USERNAME/Dragonfire.git
  1. 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.

Install Dragonfire in Development Mode

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 sudo rights.

git clone https://github.com/YOUR-USERNAME/Dragonfire.git
cd Dragonfire/
chmod +x install.sh
sudo ./install.sh --dev --pip

Use It

Try to experience every command listed in README.md. Please watch this playlist if you did not understand how to use Dragonfire.

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 PHOTO EDITOR, 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.

About Packaging

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.

How Can I Contribute?

Decide What To Do

Reporting Bugs

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.

Suggesting Enhancements

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.

Projects

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 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 beginner issues.
  • 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 👇

Push & Pull

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

Now cd into the local clone of your fork. Wherever the folder of Dragonfire is:

cd Dragonfire/

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.

Step 5: Creating a Pull Request

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.

Styleguides

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
    • 💡 :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

Python Styleguide

All Python must adhere to PEP 8.

Troubleshooting

See the Troubleshooting guide.

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

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.

We use Google Style Python Docstrings and Sphinx to build the documentation.

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/