CONTRIBUTING.md 3.7 KB
Newer Older
Hugo Posnic's avatar
Hugo Posnic committed
1
# Contributing
2 3 4 5 6 7

Contributions are welcome, and they are greatly appreciated! Every
little bit helps, and credit will always be given.

You can contribute in many ways:

Hugo Posnic's avatar
Hugo Posnic committed
8
## Types of Contributions
9

Hugo Posnic's avatar
Hugo Posnic committed
10
### Report Bugs
11

Ramon Buldó's avatar
Ramon Buldó committed
12
Report bugs at https://github.com/manjaro/pacman-mirrors/issues.
13 14

If you are reporting a bug, please include:
Hugo Posnic's avatar
Hugo Posnic committed
15 16 17
- Your operating system name and version.
- Any details about your local setup that might be helpful in troubleshooting.
- Detailed steps to reproduce the bug.
18

Hugo Posnic's avatar
Hugo Posnic committed
19
### Fix Bugs
20 21 22 23

Look through the GitHub issues for bugs. Anything tagged with "bug"
is open to whoever wants to implement it.

Hugo Posnic's avatar
Hugo Posnic committed
24
### Implement Features
25 26 27 28

Look through the GitHub issues for features. Anything tagged with "feature"
is open to whoever wants to implement it.

Hugo Posnic's avatar
Hugo Posnic committed
29
### Write Documentation
30 31 32 33 34

pacman-mirrors could always use more documentation, whether as part of the
official pacman-mirrors docs, in docstrings, or even on the web in blog posts,
articles, and such.

35 36 37 38
### Translations

Help us to ship pacman-mirrors in your language by helping our translators on [Transifex](https://www.transifex.com/manjarolinux/manjaro-pacman-mirrors/dashboard/).

Hugo Posnic's avatar
Hugo Posnic committed
39
### Submit Feedback
40

Ramon Buldó's avatar
Ramon Buldó committed
41
The best way to send feedback is to file an issue at https://github.com/manjaro/pacman-mirrors/issues.
42 43

If you are proposing a feature:
Hugo Posnic's avatar
Hugo Posnic committed
44 45 46
- Explain in detail how it would work.
- Keep the scope as narrow as possible, to make it easier to implement.
- Remember that this is a volunteer-driven project, and that contributions
47 48
  are welcome :)

Hugo Posnic's avatar
Hugo Posnic committed
49
## Get Started!
50 51 52 53

Ready to contribute? Here's how to set up `pacman-mirrors` for local development.

1. Fork the `pacman-mirrors` repo on GitHub.
Hugo Posnic's avatar
Hugo Posnic committed
54
2. Clone your fork locally:
55

Hugo Posnic's avatar
Hugo Posnic committed
56
    $ `git clone git@github.com:your_name_here/pacman-mirrors.git`
57

Hugo Posnic's avatar
Hugo Posnic committed
58
3. Install your local copy into a virtualenv. Assuming you have [virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/en/latest/) installed, this is how you set up your fork for local development:
Hugo Posnic's avatar
Hugo Posnic committed
59 60 61
    - $ `mkvirtualenv pacman-mirrors`
    - $ `cd pacman-mirrors/`
    - $ `python setup.py develop`
62

Hugo Posnic's avatar
Hugo Posnic committed
63
4. Create a branch for local development:
64

Hugo Posnic's avatar
Hugo Posnic committed
65
    $ `git checkout -b name-of-your-bugfix-or-feature`
66 67 68

   Now you can make your changes locally.

Hugo Posnic's avatar
Hugo Posnic committed
69 70 71 72
5. When you're done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:
    - $ `flake8 pacman-mirrors tests`
    - $ `python setup.py test`
    - $ `tox`
73

Hugo Posnic's avatar
Hugo Posnic committed
74
    To get flake8 and tox, just pip install them into your virtualenv.
75

Hugo Posnic's avatar
Hugo Posnic committed
76 77 78 79
6. Commit your changes and push your branch to GitHub:
    - $ `git add .`
    - $ `git commit -m "Your detailed description of your changes."`
    - $ `git push origin name-of-your-bugfix-or-feature`
80 81 82

7. Submit a pull request through the GitHub website.

Hugo Posnic's avatar
Hugo Posnic committed
83
## Pull Request Guidelines
84 85 86 87 88 89

Before you submit a pull request, check that it meets these guidelines:

1. The pull request should include tests.
2. If the pull request adds functionality, the docs should be updated. Put
   your new functionality into a function with a docstring, and add the
Hugo Posnic's avatar
Hugo Posnic committed
90
   feature to the list in README.md.
91
3. The pull request should work for Python 3.4+, and for PyPy. Check
Ramon Buldó's avatar
Ramon Buldó committed
92
   https://travis-ci.org/manjaro/pacman-mirrors/pull_requests
93 94
   and make sure that the tests pass for all supported Python versions.

Hugo Posnic's avatar
Hugo Posnic committed
95
## Tips
96

Hugo Posnic's avatar
Hugo Posnic committed
97
To run a subset of tests:
98

Hugo Posnic's avatar
Hugo Posnic committed
99
    $ `python -m unittest tests.test_pacman_mirrors`
Frede Hundewadt's avatar
Frede Hundewadt committed
100 101 102 103

Developing environment

1. An editor of choice e.g.
104
   * Visual Studio Code `yay -S visual-studio-code`
Frede Hundewadt's avatar
Frede Hundewadt committed
105 106
   * PyCharm Community `pacman -Syu pycharm-community`
2. Pandoc converter `pacman -Syu pandoc`
107
3. Python environment  
Frede Hundewadt's avatar
Frede Hundewadt committed
108
    ```
109
    sudo pacman -Syu python-pip virtualenvwrapper
Frede Hundewadt's avatar
Frede Hundewadt committed
110
    mkvirtualenv pacman-mirrors
Frede Hundewadt's avatar
Frede Hundewadt committed
111
    python setup.py develop
112
    pip install mkdocs tox coverage babel flake8 npyscreen transifex-client
Frede Hundewadt's avatar
Frede Hundewadt committed
113 114
    
    ```