Skip to content

Latest commit

 

History

History
323 lines (233 loc) · 17.4 KB

CONTRIBUTING.md

File metadata and controls

323 lines (233 loc) · 17.4 KB
Raw

Contributing to T_System

✨ First off all, thanks for taking the time to contribute! ✨

The following is a set of guidelines for contributing to T_System an open source (non-)moving objects tracking system via two axis camera motion (and as optionally n joint robotic arm) project, which is hosted in the connected-life 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 T_System's Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to cem.baybars@gmail.com.

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 Raspbian
Package managers APT, pip
Languages English

Supported Distributions: Raspbian. This release is fully supported. Any other Debian based ARM architecture 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 connected-life/T_System repository.
  2. In the top-right corner of the page, click Fork.

That's it! Now, you have a fork of the original T_System repository under your account.

Step 3: Create a local clone of your fork

Right now, you have a fork of the T_System 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 T_System 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/T_System.git
  1. Press Enter. Your local clone will be created:
git clone https://github.com/YOUR-USERNAME/T_System.git
Cloning into 'T_System'...
remote: Enumerating objects: 1863, done.
remote: Total 1863 (delta 0), reused 0 (delta 0), pack-reused 1863
Receiving objects: 100% (1863/1863), 21.48 MiB | 2.04 MiB/s, done.
Resolving deltas: 100% (1253/1253), done.
Checking connectivity... done.

Install T_System in Development Mode

You need to install T_System with sudo rights, even if you are installing editable/development mode.

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

Use It

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

If you face with a problem while installing or using T_System 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.

Choice for Code Editor

We use PyCharm 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 T_System then first 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 T_System? 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 T_System is:

cd T_System/

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

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.

Style Guides

Available Grammar

  • @TODO: Something to be done
  • @FIXME: Bug Report, should be corrected, Marked with 🐛 Commit
  • @CHANGED: Version Changes together with @SINCE DocComment, Usually Marked with 🔥 or ⚡ Commits
  • @XXX: Warn other programmers of problematic or misguiding code
  • @IDEA: A New Idea or Proof-of-Concept, Marked with 💡 Commit
  • @HACK: Workaround or Customer Customizations, Marked with 🎀 Commit
  • @NOTE: Add attention to something Important
  • @REVIEW: Needs to be Audited/Reviewed Immediately, Usually Marked with 🚧 Commit

Bug Report

  1. Add @FIXME Comment above SourceCode where Bug/Exception was Occurred.
  2. Write Additional Information:
    1. Steps to Reproduce the Error
    2. Exception Message and Code
    3. Expected Result
    4. Actual Result
    5. Environment Detail
  3. Mention the Task ID in Format {T###}.
  4. (optional) Add Screenshots in Format {F###}(Phabricator Specific).
  5. Commit the Comments(with 🐛 Emoji), also include Items 2.B, 3 & 4 in Commit Message too.
  6. Award that Task with Manufacturing Defect Token(Phabricator Specific).

Notes

  • Do NOT edit Contents of Vendor files(Composer, Bower, ...).
  • Grammars Should Appear in a List/Window in Your IDE of Choice(PHPStorm).
  • There Must be an Audit for this Bug(Commit) Appear in Phabricator.
  • These Kind of Bug Reports Remain in History of VCS for future References of that Scope of Code.
  • All Attached Files & Commit Reference HashTag will be Referenced in the Phabricator Task View.
  • These Audits May become Tasks Later.

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:

Emoji Raw Emoji Code Description
🎨 :art: when improving the format/structure of the code
📰 :newspaper: when creating a new file
📝 :pencil: when performing minor changes/fixing the code or language
🐎 :racehorse: when improving performance
📚 :books: when writing docs
📝 :memo: when changing/improving docs
🐛 :bug: when reporting a bug, with @FIXMEComment Tag
🚑 :ambulance: when fixing a bug
🐧 :penguin: when fixing something on Linux
🍎 :apple: when fixing something on Mac OS
🏁 :checkered_flag: when fixing something on Windows
🔥 :fire: when removing code or files, maybe with @CHANGED Comment Tag
🚜 :tractor: when change file structure. Usually together with 🎨
🔨 :hammer: when refactoring code
☔ :umbrella: when adding tests
🔬 :microscope: when adding code coverage
💚 :green_heart: when fixing the CI build
🔒 :lock: when dealing with security
⬆️ :arrow_up: when upgrading dependencies
⬇️ :arrow_down: when downgrading dependencies
⏩ :fast_forward: when forward-porting features from an older version/branch
⏪ :rewind: when backporting features from a newer version/branch
👕 :shirt: when removing linter/strict/deprecation warnings
💄 :lipstick: when improving UI/Cosmetic
♿ :wheelchair: when improving accessibility
🌐 :globe_with_meridians: when dealing with globalization/internationalization/i18n/g11n
🚧 :construction: WIP(Work In Progress) Commits, maybe with @REVIEW Comment Tag
💎 :gem: New Release
🥚 :egg: New Release with Python egg
🎡 :ferris_wheel: New Release with Python wheel package
🔖 :bookmark: Version Tags
🎉 :tada: Initial Commit
🔈 :speaker: when Adding Logging
🔇 :mute: when Reducing Logging
✨ :sparkles: when introducing New Features
⚡ :zap: when introducing Backward-InCompatible Features, maybe with @CHANGED Comment Tag
💡 :bulb: New Idea, with @IDEA Comment Tag
❄️ :snowflake: changing Configuration, Usually together with 🐧 or 🎀 or 🚀
🎀 :ribbon: Customer requested application Customization, with @HACK Comment Tag
🚀 :rocket: Anything related to Deployments/DevOps
🐘 :elephant: PostgreSQL Database specific (Migrations, Scripts, Extensions, ...)
🐬 :dolphin: MySQL Database specific (Migrations, Scripts, Extensions, ...)
🍃 :leaves: MongoDB Database specific (Migrations, Scripts, Extensions, ...)
🏦 :bank: Generic Database specific (Migrations, Scripts, Extensions, ...)
🐳 :whale: Docker Configuration
🤝 :handshake: when Merge files
🍒 :cherries: when Commit Arise from one or more Cherry-Pick Commit(s)

Python Style Guide

All Python must adhere to PEP 8.

References