coala Documentation Release 0.7.0 The coala Developers June 22, 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 coala Tutorial 5 2.1 Prerequisites...............................................5 2.2 Get Some Code..............................................5 2.3 Let’s Start!................................................5 2.4 Sections..................................................6 2.5 Auto-applying results..........................................7 2.6 Setting Inheritance............................................8 2.7 Ignoring Issues..............................................8 2.8 Enabling/Disabling Sections.......................................9 2.9 Show bears’ information.........................................9 2.10 Continuing the Journey.......................................... 10 3 The .coafile Specification 11 3.1 Naming, Scope and Location...................................... 11 3.2 Setting Inheritance............................................ 11 4 Glob - Extended unix style pathname expansion 13 4.1 Syntax.................................................. 13 4.2 Examples................................................. 13 5 Exit Codes 17 6 External APIs 19 6.1 DBus................................................... 19 7 Git Hooks 21 7.1 Pre Commit Hooks............................................ 21 8 Shell Autocompletion 23 9 coala in a Container 25 9.1 coala on GitLab CI............................................ 25 9.2 Troubleshooting GitLab CI....................................... 25 i 10 Development Setup Notes 27 10.1 Virtualenv................................................ 27 10.2 Repositories............................................... 27 10.3 Installing from Git............................................ 27 10.4 Building Documentation......................................... 28 11 Guide to Write a Bear 29 11.1 What is a bear?.............................................. 29 11.2 A Hello World Bear........................................... 29 11.3 Communicating with the User...................................... 30 11.4 Results.................................................. 31 11.5 Bears Depending on Other Bears.................................... 32 11.6 Hidden Results.............................................. 32 12 How to use LocalBearTestHelper to test your bears 35 12.1 Understanding through examples.................................... 35 12.2 A Final Note............................................... 37 13 Linter Bears 39 13.1 Why is This Useful?........................................... 39 13.2 What do we Need?............................................ 39 13.3 Writing the Bear............................................. 39 13.4 Using Severities............................................. 41 13.5 Using the corrected Output Format................................. 42 13.6 Adding Settings to our Bear....................................... 42 13.7 Finished Bear............................................... 43 13.8 Running and Testing our Bear...................................... 44 13.9 Where to Find More............................................. 44 14 Bears That Can Suggest And Make Corrections 45 15 Git tutorial 47 15.1 How to install Git............................................ 47 15.2 Getting started with coala ........................................ 47 15.3 Grabbing coala on your local machine................................. 47 15.4 Getting to work.............................................. 48 15.5 Creating a new branch.......................................... 48 15.6 Checking your work........................................... 48 15.7 Adding the files and commiting..................................... 48 15.8 Pushing the commit........................................... 49 15.9 Creating a Pull Request......................................... 49 15.10 Follow-up................................................. 49 15.11 Keeping your fork in sync........................................ 50 15.12 Squashing your commits......................................... 50 15.13 Useful Git commands.......................................... 51 16 Welcome to the Newcomers guide! 53 16.1 Meet the community!.......................................... 53 16.2 Start working............................................... 53 16.3 Get help with git............................................. 53 16.4 Picking up an issue............................................ 53 16.5 Things to do before pushing....................................... 54 16.6 Sending your changes.......................................... 54 16.7 Creating a Pull Request ....................................... 54 16.8 What to do after creating a Pull Request .............................. 54 ii 17 Getting Involved 57 18 Codestyle for coala 59 18.1 Additional Style Guidelines....................................... 59 19 Introduction 61 19.1 What Makes a Good Commit...................................... 61 19.2 How to Write Good Commit Messages................................. 61 19.3 Why Do We Need Good Commits?................................... 63 20 Testing 65 20.1 Executing our Tests........................................... 65 20.2 Using test coverage............................................ 65 21 Reviewing 67 21.1 Review Process.............................................. 67 21.2 Continous Integration.......................................... 67 21.3 Reviewing Commits........................................... 67 22 Introduction 69 22.1 Actually Writing a Test......................................... 69 22.2 setUp() and tearDown() ...................................... 71 22.3 Kickstart................................................. 71 23 Writing Documentation 73 24 Coverage Installation Hints for OSX Users: 75 24.1 1. Make sure you have installed Xcode and Homebrew.......................... 75 24.2 2. Install Python3............................................. 75 24.3 3. Create Virtual environments with pyvenv............................... 75 24.4 4. Virtualenvwrapper with Python 3:.................................. 75 24.5 Finally!.................................................. 76 25 A Hitchhiker’s Guide to Git(1): Genesis 77 25.1 Introduction............................................... 77 25.2 What’s Git for Anyway?......................................... 79 25.3 Setting Up Git.............................................. 79 25.4 Create a Repository........................................... 79 25.5 Creating a God Commit......................................... 80 25.6 Inspecting What Happened........................................ 82 25.7 Creating a Child Commit......................................... 83 25.8 A Glance At Our History......................................... 84 25.9 Configuring Git Even Better....................................... 85 25.10 Conclusion................................................ 86 26 coalib 87 26.1 coalib package.............................................. 87 27 What is coala? 159 28 What do I get? 161 28.1 As a User................................................. 161 28.2 As a Developer.............................................. 161 29 Status and Stability of the Project 163 iii 30 Indices and tables 165 Python Module Index 167 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.7.0 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. You may already have this installed as virtualenv or pyvenv. If you do not, this can be done with pip3 easily: $ pip3 install virtualenv Once you have virtualenv installed, just