|
1 | 1 | # Hail the contributors! |
2 | | -My eternal thanks to you, as _YOU_ make this project live and thrive! |
| 2 | +Eternal thanks to you, as _YOU_ make this project live and thrive! |
3 | 3 |
|
4 | | -## Contributing is easy, baby! |
5 | | -... and also welcome! |
| 4 | +*Contributing is easy, baby!* |
6 | 5 |
|
7 | | -## Table of Contents |
8 | | -If you're eager to start contributing, please read the [quick guide](#quick_guide)... |
| 6 | +You will find all of the details to get started [on the official documentation website](https://pyowm.readthedocs.io/) |
9 | 7 |
|
10 | | -..or dive deeper: |
11 | | - - [Installing development dependencies](#inst_dev_deps) |
12 | | - - [Guidelines for code branching](#guids_branching) |
13 | | - - [Versioning guidelines](#guids_versioning) |
14 | | - - [Design guidelines](#guids_design) |
| 8 | +## Quick guide on code contributions |
| 9 | +If you're eager to start coding on PyOWM, please follow these steps: |
15 | 10 |
|
16 | | - |
17 | | -<a name="quick_guide"></a> |
18 | | -## Quick Guide |
19 | | -A few simple steps: |
20 | 11 | 1. Fork the PyOWM repository |
21 | 12 | 2. On your fork, work on the **development branch** (_not the master branch!!!_) or on a **ad-hoc topic branch**. Don't forget to insert your name in the `CONTRIBUTORS.md` file! |
22 | | - 3. Submit a [pull request](https://help.github.com/articles/about-pull-requests/) |
23 | | - |
24 | | -<a name="inst_dev_deps"></a> |
25 | | -## Installing development dependencies |
26 | | -From the project root folder, just run: |
27 | | - |
28 | | -`pip install -r dev-requirements.txt` |
29 | | - |
30 | | -It is adviced that you do it on a `virtualenv` or, if you prefer to spin up the whole dev environment with just one command, you can run the PyOWM Docker image: |
31 | | - |
32 | | -`docker run -d --name pyowm csparpa/pyowm` |
33 | | - |
34 | | -<a name="guids_branching"></a> |
35 | | -## Guidelines for code branching |
36 | | -The project adopts @nvie's branching model: |
37 | | - |
38 | | -- the "develop" branch contains work-in-progress code |
39 | | -- new "feature" branches can be opened by any contributor from the "develop" branch. Each feature branch adds a new feature/enhancement |
40 | | -- new "hotfix" branches can be opened by any contributor from the "develop" branch. Each hotfix fixes an urgent bug that impacts the current version of PyOWM. Hotfixes will be merged back in both "master" and "develop" branches by me |
41 | | -- the "master" branch will contain only stable code and the "develop" branch will be merged back into it only when a milestone is completed or hotfixs need to be applied. Merging of "develop" into "master" will be done by me when releasing - so please **never apply your modifications to the master branch!!!** |
42 | | - |
43 | | -### So how do I submit bugfixes? |
44 | | -That's simple! Just: |
45 | | - |
46 | | -1. File a bug issue on GitHub |
47 | | -2. Fork the repo on GitHub |
48 | | -3. Create a new branch from the development, name it *hotfix/xxx* where xxx is a very short description of the bug, eg: hotfix/wind-speed-neglected |
49 | | -4. Work on that new branch - commit, commit, commit |
50 | | -5. Let's improve the code quality of PyOWM: if you can, write at least one unit test that proves that the bug has been correctly fixed |
51 | | -6. Issue a pull request and name it after the bug issue you've opened - please make sure you work on the *develop* branch! |
52 | | -7. If I'm not quick on checking the pull request, please ping me! |
53 | | - |
54 | | -### ...and how do I submit new feature requests? |
55 | | -That's simple as well! |
56 | | - |
57 | | -1. Open an issue on GitHub (describe in detail the feature you're proposing) |
58 | | -2. Depending on the entity of the request: |
59 | | - - if it's going to be a breaking change, the feature will be scheduled for embedding into the next major release - so no code shall be provided by then |
60 | | - - if it's only an enhancement, please proceed with the above workflow and submit a pull request from a *feature/xxx* branch you'll create on your fork |
61 | | - |
62 | | -<a name="guids_versioning"></a> |
63 | | -## Versioning guidelines |
64 | | -Since version 2.2 PyOWM adopts [Semantic Versioning](http://semver.org/). |
65 | | - |
66 | | -<a name="guids_design"></a> |
67 | | -## Design guidelines |
68 | | - |
69 | | -+ We're up for honey-sweet software APIs: please use user-friendly and |
70 | | -meaningful names for almost any code name (functions, endpoints wrapping, etc). |
71 | | - |
72 | | -+ Be platform-agnostic. |
73 | | - |
74 | | -+ Do not modify in any way the data content sent by the OWM web API: we just |
75 | | -chunk it in little pieces so that they can be stored into the object model. |
76 | | - |
77 | | -+ Never try to forecast/presume the ways the library clients will use the data. |
78 | | - |
79 | | -+ Design decision: for the moment, we admittedly don't support the following |
80 | | - OWM web API features regarding endpoints invocation: |
81 | | - |
82 | | - * specification of metric/imperial units - the library itself provides this |
83 | | - capability |
84 | | - * specification of output locale: unsupported at the moment |
85 | | - * specification of output format (XML, HTML, ...) - the library itself |
86 | | - provides this capability, but only limited to XML and JSON as HTML is |
87 | | - presentation-oriented and therefore less suitable for data markup |
88 | | - * specification of JSONP callbacks - only applies to Javascript codes |
89 | | - |
90 | | -+ The JSON documents that come into the OWM web API responses' payloads does not |
91 | | -show a uniform structure: this means that for API endpoints returning similar |
92 | | -data, different JSON structuring of these data must be expected and therefore |
93 | | -we must provide specific parsers for JSON data coming from each OWM API response |
94 | | -(possibly, not for EVERY different invoked endpoint!) |
95 | | - |
96 | | -+ Provide convenience classes that make easy for the user to exploit data coming |
97 | | -from the OWM web API, but let these conveniences be independent from the "raw |
98 | | -API wrapping" code. This means: the API wrapping code is the focus point, while |
99 | | -convenience classes are good to provide, but must be kept "an opation" for the |
100 | | -user. |
101 | | - |
102 | | -+ Rely on HTTP status codes. Unfortunately, OWM web API does not return error |
103 | | -codes in HTTP headers section but provides them in the payload in a JSON document! |
104 | | -Therefore we have to read the payload in order to know the outcome of the HTTP |
105 | | -request processing. |
106 | | - |
107 | | -+ The OWM web API has a bug when you specifiy the number of results you want to |
108 | | -be returned when querying weather for multiple locations. |
109 | | -These calls: |
110 | | - |
111 | | - http://api.openweathermap.org/data/2.5/find?q=London&type=accurate&cnt=2 |
112 | | - http://api.openweathermap.org/data/2.5/find?q=London&type=like&cnt=2 |
113 | | - |
114 | | -both returns 3 elements (it should have given only 2), while this call |
115 | | - |
116 | | - http://api.openweathermap.org/data/2.5/find?lat=57&lon=-2.15&cnt=3 |
117 | | - |
118 | | -returns exactly 3 elements. |
119 | | -This bug is evidently non-uniform and we don't want our library to show it |
120 | | -to its users. |
121 | | - |
122 | | -+ Another annoying mis-feature in the OWM web API is the lack of distinction |
123 | | -between a "404 (meteostation not found)" condition and a "no data found for the |
124 | | -meteostation" condition when querying for historic weather data for a specific |
125 | | -meteostation. Both of the conditions are mapped to an HTTP response having 200 |
126 | | -as status code and containing an empty list of results in the payload, which |
127 | | -is clearly not what one is expecting when the queried meteostation is not found |
128 | | -in the server-side meteotations datastore! |
| 13 | + 3. TEST YOUR CODE please! [Here's the gig](https://github.com/csparpa/pyowm/wiki/Notes-on-testing) |
| 14 | + 4. Submit a [pull request](https://help.github.com/articles/about-pull-requests/) |
0 commit comments