summaryrefslogtreecommitdiffstats
path: root/CONTRIBUTING.md
blob: ad22cdf58afacf81a193c82970b0f5a8ff565a3b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
# Development Guide

This is a guide for developers who would like to contribute to this project. It is recommended to use Python 3.6 and above for development.

If you're interested in contributing to litecli, thank you. We'd love your help!
You'll always get credit for your work.

## GitHub Workflow

1. [Fork the repository](https://github.com/dbcli/litecli) on GitHub.

2. Clone your fork locally:
    ```bash
    $ git clone <url-for-your-fork>
    ```

3. Add the official repository (`upstream`) as a remote repository:
    ```bash
    $ git remote add upstream git@github.com:dbcli/litecli.git
    ```

4. Set up a [virtual environment](http://docs.python-guide.org/en/latest/dev/virtualenvs)
   for development:

    ```bash
    $ cd litecli
    $ pip install virtualenv
    $ virtualenv litecli_dev
    ```

    We've just created a virtual environment that we'll use to install all the dependencies
    and tools we need to work on litecli. Whenever you want to work on litecli, you
    need to activate the virtual environment:

    ```bash
    $ source litecli_dev/bin/activate
    ```

    When you're done working, you can deactivate the virtual environment:

    ```bash
    $ deactivate
    ```

5. Install the dependencies and development tools:

    ```bash
    $ pip install -r requirements-dev.txt
    $ pip install --editable .
    ```

6. Create a branch for your bugfix or feature based off the `master` branch:

    ```bash
    $ git checkout -b <name-of-bugfix-or-feature>
    ```

7. While you work on your bugfix or feature, be sure to pull the latest changes from `upstream`. This ensures that your local codebase is up-to-date:

    ```bash
    $ git pull upstream master
    ```

8. When your work is ready for the litecli team to review it, push your branch to your fork:

    ```bash
    $ git push origin <name-of-bugfix-or-feature>
    ```

9. [Create a pull request](https://help.github.com/articles/creating-a-pull-request-from-a-fork/) on GitHub.


## Running the Tests

While you work on litecli, it's important to run the tests to make sure your code
hasn't broken any existing functionality. To run the tests, just type in:

```bash
$ ./setup.py test
```

litecli supports Python 2.7 and 3.4+. You can test against multiple versions of
Python by running tox:

```bash
$ tox
```


### CLI Tests

Some CLI tests expect the program `ex` to be a symbolic link to `vim`.

In some systems (e.g. Arch Linux) `ex` is a symbolic link to `vi`, which will
change the output and therefore make some tests fail.

You can check this by running:
```bash
$ readlink -f $(which ex)
```


## Coding Style

litecli uses [black](https://github.com/ambv/black) to format the source code. Make sure to install black.

It's easy to check the style of your code, just run:

```bash
$ ./setup.py lint
```

If you see any style issues, you can automatically fix them by running:

```bash
$ ./setup.py lint --fix
```

Be sure to commit and push any stylistic fixes.