|
1 | | -Any and all contributions are welcome and appreciated. To make it easy |
2 | | -to keep things organized, this project uses the |
3 | | -[general guidelines](https://guides.github.com/introduction/flow/) |
4 | | -for the fork-branch-pull request model for github. Briefly, this means: |
| 1 | +[](https://jazzband.co/) |
5 | 2 |
|
6 | | -1. Make sure your fork's `master` branch is up to date: |
7 | | - |
8 | | - git remote add deanmalmgren https://github.com/deanmalmgren/textract.git |
9 | | - git checkout master |
10 | | - git pull deanmalmgren/master |
11 | | - |
12 | | -2. Start a feature branch with a descriptive name about what you're |
13 | | - trying to accomplish: |
14 | | - |
15 | | - git checkout -b csv-support |
16 | | - |
17 | | -3. Make commits to this feature branch (`csv-support`, in this case) |
18 | | - in a way that other people can understand with good commit messages |
19 | | - to explain the changes you've made: |
20 | | - |
21 | | - emacs textract/parsers/csv_parser.py |
22 | | - git add textract/parsers/csv_parser.py |
23 | | - git commit -m 'added csv_parser' |
24 | | - |
25 | | -4. If an issue already exists for the code you're contributing, use |
26 | | - [issue2pr](http://issue2pr.herokuapp.com/) to attach your code to |
27 | | - that issue: |
28 | | - |
29 | | - git push origin csv-support |
30 | | - chrome http://issue2pr.herokuapp.com |
31 | | - # enter the issue URL, HEAD=yourusername:csv-support, Base=master |
32 | | - |
33 | | - If the issue doesn't already exist, just send a pull |
34 | | - request in the usual way: |
35 | | - |
36 | | - git push origin csv-support |
37 | | - chrome http://github.com/deanmalmgren/textract/compare |
38 | | - |
39 | | - |
40 | | -Common contributions: support for new file type |
41 | | ------------------------------------------------ |
42 | | - |
43 | | -This project has really taken off, much more so than I would have |
44 | | -thought (thanks everybody!). To help new contributors, I thought I'd |
45 | | -jot down some notes for one of the more common contributions---how to |
46 | | -add support for hitherto unsupported file type `.abc123`: |
47 | | - |
48 | | -* write a `Parser` class in `textract/parsers/abc123_parser.py` that |
49 | | - inherits from `textract.parsers.utils.BaseParser` or |
50 | | - `textract.parsers.utils.ShellParser` and implements the |
51 | | - `extract(self, filename, **kwargs)` method. |
52 | | - |
53 | | -* add a test file in `tests/abc123/raw_text.abc123`, run textract on |
54 | | - it like this: |
55 | | - |
56 | | - ```shell |
57 | | - textract tests/abc123/raw_text.abc123 > tests/abc123/raw_text.txt |
58 | | - ``` |
59 | | - |
60 | | - and add the basic test suite by creating |
61 | | - a file called `tests/test_abc123.py` with content that looks |
62 | | - something like this: |
63 | | - |
64 | | - ```python |
65 | | - # tests/test_abc123.py |
66 | | - import unittest |
67 | | - |
68 | | - import base |
69 | | - |
70 | | - |
71 | | - class Abc123TestCase(unittest.TestCase, base.BaseParserTestCase): |
72 | | - extension = 'abc123' |
73 | | - ``` |
74 | | - |
75 | | - now you should be able to run tests on your parser with `nosetests |
76 | | - tests/test_abc123.py` or the tests for every parser with `nosetests`. |
77 | | - |
78 | | -* if your package relies on any external sources, be sure to add them |
79 | | - in either `requirements/python` (for python packages) or |
80 | | - `requirements/debian` (for debian packages) and update the |
81 | | - installation documentation accordingly in `docs/installation.rst`. |
82 | | - |
83 | | -* add documentation about the awesome new file format this is being |
84 | | - supported in `docs/index.rst` and be sure to give yourself a pat on |
85 | | - the back by updating the changelog in `docs/changelog.rst` |
86 | | - |
87 | | -* finally, make sure the entire test suite passes by running |
88 | | - `./tests/run.py` and fix any lingering problems (usually PEP-8 |
89 | | - nonsense). |
90 | | - |
91 | | - |
92 | | -Style guidelines |
93 | | ----------------- |
94 | | - |
95 | | -As a general rule of thumb, the goal of this package is to be as |
96 | | -readable as possible to make it easy for novices and experts alike to |
97 | | -contribute to the source code in meaningful ways. Pull requests that |
98 | | -favor cleverness or optimization over readability are less likely to be |
99 | | -incorporated. |
100 | | - |
101 | | -To make this notion of "readability" more concrete, here are a few |
102 | | -stylistic guidelines that are inspired by other projects and we |
103 | | -generally recommend: |
104 | | - |
105 | | -- write functions and methods that can `fit on a screen or two of a |
106 | | - standard |
107 | | - terminal <https://www.kernel.org/doc/Documentation/CodingStyle>`_ |
108 | | - --- no more than approximately 40 lines. |
109 | | - |
110 | | -- unless it makes code less readable, adhere to `PEP |
111 | | - 8 <http://legacy.python.org/dev/peps/pep-0008/>`_ style |
112 | | - recommendations --- use an appropriate amount of whitespace. |
113 | | - |
114 | | -- `code comments should be about *what* is being done, not *how* it is |
115 | | - being done <https://www.kernel.org/doc/Documentation/CodingStyle>`_ |
116 | | - --- that should be self-evident from the code itself. |
| 3 | +This is a [Jazzband](https://jazzband.co/) project. By contributing you agree to |
| 4 | +abide by the [Contributor Code of Conduct](https://jazzband.co/about/conduct) |
| 5 | +and follow the [guidelines](https://jazzband.co/about/guidelines). |
0 commit comments