Skip to content

Commit

Permalink
Merge branch 'release-1.4.6'
Browse files Browse the repository at this point in the history
  • Loading branch information
@Milind220
Milind220 committed Mar 22, 2022
2 parents 3461da7 + ca58dea commit bef2e41
Show file tree
Hide file tree
Showing 5 changed files with 155 additions and 100 deletions.
18 changes: 18 additions & 0 deletions .pre-commit-config.yaml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
repos:
- repo: https://github.com/pre-commit/mirrors-mypy
rev: 'v0.941' # Use the sha / tag to point at specific version
hooks:
- id: mypy
- repo: https://github.com/psf/black
rev: '22.1.0'
hooks:
- id: black
- repo: https://github.com/PyCQA/flake8
rev: '4.0.1'
hooks:
- id: flake8
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: 'v4.1.0'
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
217 changes: 124 additions & 93 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,137 +2,166 @@

:tada::+1: First off, thanks for taking the time to contribute! :tada::+1:

The following is a set of guidelines for contributing to [Ozone](https://github.com/Milind220/Ozone). These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.
It might not be obvious but we appreciate all forms of contribution.

> **Note:** One very important thing is to make sure you only make PR's to the `dev` branch and not the `main` branch. The main branch is stable and should not be modified unless there's a new release.
The following is a set of guidelines for contributing to [Ozone](https://github.com/Milind220/Ozone). These are mostly guidelines, not rules. Use your best judgment. Feel free to propose changes to this document in a pull request.

#### Table Of Contents
> **Important note:** Make sure you make PRs to `dev` branch, not `main`. See [below](#making-a-pull-request) for more information.
[I don't want to read this whole thing, I just have a question!!!](#i-dont-want-to-read-this-whole-thing-i-just-have-a-question)
#### Table of Contents

[What should I know before I get started?](#what-should-i-know-before-i-get-started)
* [File Structure](#file-structure)
- [How Can I Contribute?](#how-can-i-contribute)

[How Can I Contribute?](#how-can-i-contribute)
* [Reporting Bugs](#reporting-bugs)
* [Suggesting Enhancements or Feature](#suggesting-enhancements-or-features)
* [Your First Code Contribution](#your-first-code-contribution)
* [How to get an issue assigned to you](#how-to-get-an-issue-assigned-to-you)
* [Pull Requests](#pull-requests)
- [Reporting bugs](#reporting-bugs)
- [Suggesting enhancements/features](#suggesting-enhancements/features)
- [Making a pull request](#making-a-pull-request)
- [Get an issue assigned to you](#get-an-issue-assigned-to-you)

[Styleguides](#styleguides)
* [Git Commit Messages](#git-commit-messages)
* [Python Styleguide](#python-styleguide)
- [Setting Up Local Development Environment](#setting-up-local-development-environment)

[Github Branching Model](#github-branching-model)
- [Getting a local copy](#getting-a-local-copy)
- [Setting up a development environment](#setting-up-a-development-environment)
- [Pushing changes and opening a pull request](#pushing-changes-and-opening-a-pull-request)

## I don't want to read this whole thing I just have a question!!!
- [Style Guides](#style-guides)

> **Note:** Please don't file an issue to ask a question. Search for your question in issues and see if it's already been answered. Also check out the [discussions](https://github.com/Milind220/Ozone/discussions) tab to see if we've chatted about it before. Post it there if it's an idea, or in issues if there's a change to be made.
- [Commit message style guide](#git-commit-messages)
- [Python style guide](#python-style-guide)

- [Github Branching Model](#github-branching-model)

## What should I know before I get started?

### File Structure
Ozone is currently an extremely simple package.
* The package itself is in the ```src/ozone``` directory.
* [ozone.py](https://github.com/Milind220/Ozone/tree/main/src/ozone/ozone.py) contains the Ozone class that does most of the fetching of the data.
* [urls.py](https://github.com/Milind220/Ozone/tree/main/src/ozone/urls.py) contains a URLs class with the API endpoints and base urls.

## How Can I Contribute?

### Reporting Bugs
### Reporting bugs

Before creating bug reports, please check [this list](#before-submitting-a-bug-report) as you might find out that you don't need to create one. When you are creating a bug report, please [include as many details as possible](#how-do-i-submit-a-good-bug-report).
1. Before submitting a bug report, make sure to do a cursory search on [issues](https://github.com/Milind220/Ozone/issues) to see if it's already reported. If it's already reported, add a comment under the issue thread instead of opening a new one.

> **Note:** If you find a **Closed** issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one.
2. Use clear and descriptive title.

#### Before Submitting A Bug Report
3. Include in the body of the issue:

* **Perform a [cursory search](https://github.com/Milind220/Ozone/issues)** to see if the problem has already been reported. If it has **and the issue is still open**, add a comment to the existing issue instead of opening a new one.
- **Expected behavior**: What do you expect should happen?
- **Actual behavior**: What actually happened and why it's a problem?
- **Steps to reproduce the problem**. Be very specific. Give example code block. Other contributors want to run it in their device to make sure they see what you saw. Having detailed steps and examples can make it easier to demonstrate and track down a problem.
- **Version information**: What version of Python you're using? What version of Ozone? Do you install through `pip` or by cloning the Github repository? What is your OS and what version?

#### How Do I Submit A (Good) Bug Report?
Bugs are tracked as [GitHub issues](https://guides.github.com/features/issues/).
You can include screenshots/GIFs, if relevant.

* **Use a clear and descriptive title** for the issue to identify the problem.
* **Describe the steps which reproduce the problem** in as many details as possible.
* **Provide specific examples to demonstrate the steps**. Include links to files or GitHub projects, or copy/pasteable snippets. If you're providing snippets in the issue, use [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines).
* **Describe the behavior you observed after following the steps** and point out the problem with that behavior. **Explain which behavior you expected to see instead and why.**
* Feel free to **include screenshots / animated GIFs** to clearly demonstrate the problem.
* **If the problem wasn't triggered by a specific action**, describe what you were doing before the problem happened and share more information using the guidelines below.
Additionally, you can also confirm other people's bug report by running their provided code and steps in your local machine and see if the same problem shows up. Every test helps, especially if your device setup is different (i.e. has different OS or Python version) from the original bug report.

Consider providing additional context by answering these questions:
### Suggesting enhancements/features

* **Did the problem start happening recently** (e.g. after updating to a new version of Ozon3) or was this always a problem?
* **Can you reliably reproduce the issue?** If not, provide details about how often the problem happens and under which conditions it normally happens.
* **Which version of Ozon3 are youeusing?**
1. Before submitting a feature suggestion, make sure to do a cursory search in [issues](https://github.com/Milind220/Ozone/issues) to see if it's already suggested.

### Suggesting Enhancements or Features
2. Use clear and descriptive title.

This section guides you through submitting an enhancement/feature suggestion for Ozon3.
3. Lay out the details of your suggestion in the body issue. Make sure to also:

- Describe the current behavior and explain what would you like to see instead.
- Explain why your suggestion would be useful for Ozone users.

### Making a pull request

#### Before Submitting An Enhancement Suggestion
You can also make a pull request to fix an existing bug or add a feature.

Please check the [issues](https://github.com/Milind220/Ozone/issues) list, as you may find that it's already been suggested. When you are creating an enhancement suggestion.
Unsure where to begin contributing to Ozone? You can start by looking through these `first-contribution`, `beginner`, `help-wanted` issues:

#### How Do I Submit A (Good) Enhancement/Feature Suggestion?
* `first-contribution` issues should only require a few lines of code or are improvements on the documentation.
* `beginner` issues are a step up, and may involve a couple of methods/tests.
* `help-wanted` issues are slightly trickier.

Enhancement/feature suggestions are tracked as [GitHub issues](https://guides.github.com/features/issues/).
One very important thing is to make sure you only make PR's to the `dev` branch and not the `main` branch. The main branch is stable, and `dev` branch changes will be merged into `main` periodically once it's confirmed that they don't have any breaking changes.

* **Use a clear and descriptive title** for the issue to identify the suggestion/feature. Explain the idea well in the description.
* **Describe the current behavior** and **which behavior you expected to see instead**.
* **Explain why this enhancement would be useful** to most Ozon3 users.
### Get an issue assigned to you

### Your First Code Contribution
If you find an issue that you'd like to tackle - get it assigned to yourself by commenting on it with:

Unsure where to begin contributing to Ozone? You can start by looking through these `first-contribution`, `beginner`, `help-wanted` issues:
```
Hold my beer, I got this
```

* `first-contribution` should only require a few lines of code. Or are improvements are documentation.
* `beginner` issues are a step up, and may involve a couple of methods/tests.
* `help-wanted` issues are slightly trickier and require more code and logic.
## Setting Up Local Development Environment

### Getting a local copy

1. Fork this repository.

2. Clone your fork to your local device.

3. Set your fork as `origin` remote. This is usually done automatically if you're using `git clone` command. To do it manually:

```sh
git remote add origin URL_OF_YOUR_FORK
```

4. Set original repository as `upstream` remote.

```sh
git remote add upstream https://github.com/Milind220/Ozone.git
```

5. Pull from original repository to make sure you're synced up.

### How to get an issue assigned to you
```sh
git pull upstream dev:dev
```

**If you find an issue that you'd like to tackle - get it assigned to yourself by commenting on it with:**
You may want to do it once in a long while to make sure your local dev branch is in sync with the `upstream` remote.

Hold my beer, I got this
6. Checkout the `dev` branch, and make a new branch from there to make changes.

### Pull Requests (PR's)
```sh
git checkout dev
git checkout -b my-feature-branch
```

Here's how you can get started:
### Setting up a development environment

> **Note:** One very important thing is to make sure you only make PR's to the `dev` branch and not the `main` branch. The main branch is stable, and dev branch changes will be merged into it periodically once it's confirmed that they don't have any breaking changes.
1. Create and activate a virtual environment.

_SETUP_
1. Assign yourself an issue from the issues section of the repository. This makes sure that two people don't end up working on the same code concurrently.
2. **Switch to the dev branch** of the Github repository. This is where all pre-release changes and additions are made.
3. **Fork the dev branch**. This creates your own personal copy of the project, which you access through your Github profile.
4. **Clone your forked project**. This creates a copy on your computer where you can make all your changes.
5. **Set your fork as the 'origin' remote** with `git remote add origin URL_OF_YOUR_FORK`.
6. **Set the original project url as the 'upstream' remote** with `git remote add upstream https://github.com/Milind220/Ozone.git`.
7. **Pull from the original project's dev branch to make sure you're synced up** before you make your own changes. `git pull upstream dev`. Then switch to the dev branch on your computer with `git checkout dev`.
8. Whoohoo! You can now make changes to the code!
9. **Make sure to commit logical changes only**. Don't commit things that you're trying out and haven't tested.
10. When you're done, **test out the changes that you've made to the package.** Proceed if all's good.
11. **Push the changes to your forked repository**.
12. Return to your forked repo on Github and click on `compare and pull request` to begin the PR.
13. Describe your PR, Submit it and wait for it to be merged!
e.g. using Python's built-in `venv` module:

```sh
python -m venv venv
venv/scripts/activate
```

#### Also
* Follow the [styleguides](#styleguides)
* Write a detailed pull request (PR)
2. Within the virtual environment, install the requirements. Afterwards, install the package in editable mode.

You may have to complete additional work, tests, or other changes before your pull request is accepted.
```sh
pip install -r requirements.txt
pip install -e .
```

#### :tada::+1: _CONGRATULATIONS YOU MADE A PULL REQUEST_ :tada::+1:
3. Activate pre-commit hooks.

## Styleguides
```sh
pre-commit install
```

### Git Commit Messages
From this point on, pre-commit hooks will run linters and formatters automatically before every commit. If there's a problem, the commit will abort. You'll need to fix the problem before committing again.

Commmits should be made in this format:
4. Your local development environment is ready to use. Feel free to code away. Make sure to only commit logical changes that are already tested. Don't commit things you just try out and haven't tested.

5. When you're done coding, again, **test out the changes that you've made to the package.** Proceed if all is good.

### Pushing changes and opening a pull request

1. Push the changes to your forked repository.

2. Return to your forked repository on Github and click on `compare and pull request` to begin the PR. **Make sure the base branch is `dev`, not `main`.**

3. Describe your PR, submit it and wait for it to be merged! You may be required to do additional work or changes before it is merged.



## Style Guides

### Git commit messages

Commmits should be made in this format:

```
<type>[optional scope]: <description>
Expand All @@ -142,7 +171,7 @@ Commmits should be made in this format:

* fix: To show that a bug fix or patch has been made
* feat: To show that a new feature/enhancement has been added
* BREAKING CHANGE: For changes that introduce backwards incompatible updates
* BREAKING CHANGE: For changes that introduce backwards-incompatible updates
* refactor: If you've rearranged/refactored existing code by splitting it into seperate files/methods/functions/classes
* test: Any modification of tests
* ci/cd: Any addition of continuous integration/deployement tasks, such as GitHub actions
Expand All @@ -152,20 +181,22 @@ Commmits should be made in this format:

> **Note:** The above guidelines were added on 8th Mar, 2022. All commits before this time do not have these prefixes.
Here are a few other tips:
Here are a few other tips:

* Use the present tense ("Add feature" not "Added feature").
* Limit the first line to 72 characters or less.
* Add descriptions where needed, to explain your commit in more detail.

### Python style guide

* Follow the [pep8](https://www.python.org/dev/peps/pep-0008/) styleguide.
* Format with flake8 and black.
* Add docstrings with formats as shown in existing code.

* Use the present tense ("Add feature" not "Added feature")
* Limit the first line to 72 characters or less
* Add descriptions where needed, to explain your commit in more detail

### Python Styleguide
* Follow the [pep8](https://www.python.org/dev/peps/pep-0008/) styleguide
* Format with flake8 and black
* Add docstrings as shown in existing code

## Github Branching Model

Ozone branches are created using a Github branching model. In this branching model, each branch serves a purpose and offers team members a shared undestanding of the branching system.

See more information on this branching model [here](https://github.com/Milind220/Ozone/discussions/24).

4 changes: 3 additions & 1 deletion requirements.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ numpy==1.22.2
requests==2.27.1
openpyxl
ratelimit==2.2.1

mypy
flake8
black
black
pre-commit
8 changes: 6 additions & 2 deletions setup.cfg
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[metadata]
name = ozon3
version = 1.4.5
version = 1.4.6
author = Milind Sharma
author_email = [email protected]
description = A package to get air quality data using the WAQI API
Expand Down Expand Up @@ -32,4 +32,8 @@ install_requires=
requests
openpyxl
ratelimit


[flake8]
# Configure flake8 to work with black's style
max-line-length = 88
extend-ignore = E203
8 changes: 4 additions & 4 deletions setup.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,19 +9,19 @@
description="A package to get air quality data using the WAQI API",
license="GPLv3+",
url="https://github.com/Milind220/Ozone",
version="1.4.5",
download_url="https://github.com/Milind220/Ozone/archive/refs/tags/v1.4.5.tar.gz",
version="1.4.6",
download_url="https://github.com/Milind220/Ozone/archive/refs/tags/v1.4.6.tar.gz",
packages=setuptools.find_packages(),
install_requires=[
"numpy; python_version>='3'",
"pandas; python_version>='3'",
"requests; python_version>='3'",
"openpyxl; python_version>='3'",
"ratelimit; python_version>='3'"
"ratelimit; python_version>='3'",
],
python_requires=">=3.6",
classifiers=[
"Development Status :: 5 - Production/Stable", # Chose either "3 - Alpha", "4 - Beta" or "5 - Production/Stable" as the current state of your package
"Development Status :: 5 - Production/Stable",
"Intended Audience :: Developers", # Define that your audience are developers
"Topic :: Software Development :: Build Tools",
"License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
Expand Down

0 comments on commit bef2e41

Please sign in to comment.