Coala Documentation Release 0.5.2
Total Page：16
File Type：pdf, Size：1020Kb
coala Documentation Release 0.5.2 The coala Developers June 17, 2016 Home 1 coala Installation 1 1.1 System wide installation.........................................1 1.2 Installing inside a virtualenv.......................................2 1.3 Installing coala from source.......................................2 1.4 Dependencies...............................................3 2 The .coafile Specification 5 2.1 Naming, Scope and Location......................................5 2.2 Setting Inheritance............................................5 3 Glob - Extended unix style pathname expansion7 3.1 Syntax..................................................7 3.2 Examples.................................................7 4 Exit Codes 11 5 External APIs 13 5.1 DBus................................................... 13 6 Git Hooks 15 6.1 Pre Commit Hooks............................................ 15 7 coala Tutorial 17 7.1 Prerequisites............................................... 17 7.2 Get Some Code.............................................. 17 7.3 Let’s Start!................................................ 17 7.4 Sections.................................................. 18 7.5 Auto-applying results.......................................... 19 7.6 Setting Inheritance............................................ 19 7.7 Ignoring Issues.............................................. 20 7.8 Enabling/Disabling Sections....................................... 21 7.9 Show bears’ information......................................... 21 7.10 Integrating coala into Your Project.................................... 21 7.11 Continuing the Journey.......................................... 22 8 Guide to Write a Bear 23 8.1 What is a bear?.............................................. 23 8.2 A Hello World Bear........................................... 23 8.3 Communicating with the User...................................... 24 i 8.4 Results.................................................. 25 9 Linter Bears 27 9.1 Why is This Useful?........................................... 27 9.2 What do we Need?............................................ 27 9.3 Writing the Bear............................................. 27 9.4 Adding Settings to our Bear....................................... 29 9.5 Right place for ‘{filename}’....................................... 30 9.6 Finished Bear............................................... 30 9.7 Running and Testing our Bear...................................... 31 10 Bears That Can Suggest And Make Corrections 33 11 Git tutorial 35 11.1 How to install Git............................................ 35 11.2 Getting started with coala........................................ 35 11.3 Grabbing coala on your local machine.................................. 35 11.4 Getting to work.............................................. 36 11.5 Creating a new branch.......................................... 36 11.6 Checking your work........................................... 36 11.7 Adding the files and commiting..................................... 36 11.8 Pushing the commit........................................... 37 11.9 Creating a Pull Request......................................... 37 11.10 Follow-up................................................. 37 11.11 Keeping your fork in sync........................................ 38 11.12 Squashing your commits......................................... 38 11.13 Useful Git commands.......................................... 39 12 Welcome to the Newcomers guide! 41 12.1 Meet the community!.......................................... 41 12.2 Start working............................................... 41 12.3 Get help with git............................................. 41 12.4 Start working............................................... 41 12.5 Things to do before pushing....................................... 42 12.6 Sending your changes.......................................... 42 12.7 Creating a Pull Request......................................... 42 12.8 What to do after creating a PR...................................... 42 13 Getting Involved 45 14 Codestyle for coala 47 14.1 Additional Style Guidelines....................................... 47 15 Introduction 49 15.1 What Makes a Good Commit...................................... 49 15.2 How to Write Good Commit Messages................................. 49 15.3 Why Do We Need Good Commits?................................... 51 16 Testing 53 16.1 Executing our Tests........................................... 53 16.2 Using test coverage............................................ 53 17 Reviewing 55 17.1 Review Process.............................................. 55 17.2 Continous Integration.......................................... 55 ii 17.3 Reviewing Commits........................................... 55 18 Introduction 57 18.1 Actually Writing a Test......................................... 57 18.2 setUp() and tearDown() ...................................... 59 18.3 Assertions................................................ 59 18.4 Kickstart................................................. 60 19 Writing Documentation 63 20 Coverage Installation Hints for OSX Users: 65 20.1 1. Make sure you have installed Xcode and Homebrew.......................... 65 20.2 2. Install Python3............................................. 65 20.3 3. Create Virtual environments with pyvenv............................... 65 20.4 4. Virtualenvwrapper with Python 3:.................................. 65 20.5 Finally!.................................................. 66 21 A Hitchhiker’s Guide to Git(1): Genesis 67 21.1 Introduction............................................... 67 21.2 What’s Git for Anyway?......................................... 69 21.3 Setting Up Git.............................................. 69 21.4 Create a Repository........................................... 69 21.5 Creating a God Commit......................................... 70 21.6 Inspecting What Happened........................................ 72 21.7 Creating a Child Commit......................................... 73 21.8 A Glance At Our History......................................... 74 21.9 Configuring Git Even Better....................................... 75 21.10 Conclusion................................................ 76 22 coalib 77 22.1 coalib package.............................................. 77 23 What is coala? 137 24 What do I get? 139 24.1 As a User................................................. 139 24.2 As a Developer.............................................. 139 25 Status and Stability of the Project 141 26 Indices and tables 143 Python Module Index 145 iii iv CHAPTER 1 coala Installation This document contains information on how to install coala. Supported platforms are Linux and Windows. coala is known to work on OS X as well. coala is tested against CPython 3.3, 3.4 and 3.5. In order to run coala you need to install Python. It is recommended, that you install Python3 >= 3.3 from http://www.python.org. The easiest way to install coala is using pip (Pip Installs Packages). If you don’t already have pip, you can install it like described on https://pip.pypa.io/en/stable/installing.html. Note that pip is shipped with recent python versions by default. 1.1 System wide installation The simplest way to install coala is to do it system-wide. But, This is generally discouraged in favor or using a virtualenv. To install the latest most stable version of coala and supported bears system-wide, use: $ pip3 install coala-bears Note: For this and all future steps, some steps require root access (also known as administrative privileges in Win- dows). Unix based (Mac, Linux) - This can be achieved by using sudo in front of the command sudo command_name instead of command_name Windows - The easiest way on windows is to start a command prompt as an administrator and start setup.py. To install the nightly build from our master branch, you can do: $ pip3 install coala-bears --pre To install only coala (without any bears), you can do: $ pip3 install coala With --pre you can install the nightly build of the coala base without bears. 1 coala Documentation, Release 0.5.2 1.2 Installing inside a virtualenv Virtualenv is probably what you want to use during development, you’ll probably want to use it there, too. You can read more about it at their documentation - http://virtualenv.readthedocs.org First, we need to install virtualenv to the system. This can be done with pip3 easily: pip3 install virtualenv Once you have virtualenv installed, just fire up a shell and create your own environment. I usually create a project folder and a venv folder: $ virtualenv venv Now, whenever you want to work on the project, you only have to activate the corresponding environment. On Unix based systems (OSX and Linux) this can be done with: $ source venv/bin/activate And on Windows this is done with: $ venv\scripts\activate Finally, you install coala and supported bears inside the activated virtualenv with: $ pip3 install coala-bears 1.3 Installing coala from source In order to install coala from source, it is recommended to install git. See http://git-scm.com/ for further information and a downloadable installer or use your package manager on linux to get it. Note: Again, here it is recommended to install coala inside a virtualenv. This can be done by creating a virtualenv and running the installation commands after the virtualenv has been activated. After having git installed,