Skip to content

Commit

Permalink
Merge pull request #203 from whylabs/configuration-and-docs
Browse files Browse the repository at this point in the history 
Configuration and docs updates
  • Loading branch information
@naddeoa
naddeoa committed Apr 20, 2021
2 parents 36195d1 + 1d292b2 commit 5e0a5dc
Show file tree
Hide file tree
Showing 10 changed files with 399 additions and 293 deletions.
7 changes: 4 additions & 3 deletions .bumpversion.cfg
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
[bumpversion]
current_version = 0.4.5-dev1
commit = True
tag = False
parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)(\-(?P<release>[a-z]+)(?P<build>\d+))?
serialize =
Expand All @@ -14,8 +13,10 @@ values =
dev
prod

[bumpversion:file:setup.cfg]

[bumpversion:file:src/whylogs/_version.py]

[bumpversion:file:docs/conf.py]

[bumpversion:file:Makefile]

[bumpversion:file:pyproject.toml]
2 changes: 2 additions & 0 deletions .github/workflows/continuous-integration.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,8 @@ jobs:
${{ runner.os }}-pip-
- name: Install dependencies
run: make install
- name: Run build, style, and lint checks
run: make release
- name: Run tests
run: make test-system-python
- name: Coveralls Parallel
Expand Down
149 changes: 48 additions & 101 deletions DEVELOPMENT.md
View file
Original file line number Diff line number Diff line change
@@ -1,25 +1,5 @@
# Developing whylogs Python

Please take a look at this doc before contributing to whylogs python.



## Code format

The following run the linter (flake8) and formatter (black). It fails if it finds issues but they won't be automatically resolved.

```bash
make lint format
```

To automatically resolve issues, run

```bash
make format-fix
```

## Development Environment

# Environment Setup
You'll need to install poetry in order to install dependencies using the lock file in this project. Follow [their docs](https://python-poetry.org/docs/) to get it set up.

```
Expand All @@ -43,43 +23,70 @@ Poetry manages virtualenvs as well. Typically, on a project that uses virtualenv
poetry shell
```

You shouldn't have to actually do that unless you want to run some of the things that are pip installed directly. One use case would be manually running `pytest` on a single test file rather than running them all with `make test`.

## Managing Dependencies
You shouldn't have to actually do that unless you want to run some of the executables things that are installed from pypi directly. One use case would be manually running `pytest` on a single test file rather than running them all with `make test`.

Poetry manages all of the dependencies. If you need to add something then you should run the following.
## Manging Dependencies
This is done through poetry. There needs be a good reason to add dependencies that should be included in the commit message.

```
poetry add new-dependency
```bash
# Add a dependency
poetry add package-name

# Or for dev/test only dependencies
poetry add --dev new-dependency
# Add a dev only dependency that gets installed locally during dev
poetry add --dev package-name

# Update the lock file after
# Update the lock file. Run this after adding or removing things. It doesn't appear to always happen automatically.
poetry lock
```


## Testing
To run tests using the current Python environment:
# Development Details
You can run `make help` for a full list of targets that you can run. These are the ones that you'll need most often.

```

```bash
# Build everything, producing a source tar and wheel in ./dist
make

# For running tests locally
make test
```

### Coverage
# For running notebook tests
make test-notebooks

Coverage can be checked with
# For formatting and linting
make lint
make lint-fix
make format
make format-fix

```
make coverage
# Remove all generated artifacts
make clean
```

### Testing CI locally
## IDE Setup
There are a few useful plugins that are probably available for most IDEs. Using Pyrcharm, you'll want to install the Poetry and black plugins.

TODO make this a real docker file then
- [blackconnect](https://plugins.jetbrains.com/plugin/14321-blackconnect) can be configured to auto format files on save. Just run `make blackd` from a shell to set up the server and the plugin will do its thing. You need to configure it to format on save, it's off by default.
- [poetry](https://plugins.jetbrains.com/plugin/14307-poetry) plugin will make the dependencies installed by poetry available in pycharm.

you can run local github actions on ubuntu using [act](https://github.com/nektos/act). Currently, you need to build the latest docker image for ubuntu using the following dockerfile
# Publishing
Running `make publish` will upload a new version to pypi using poetry's publish logic. Follow the Push Process to bump the version appropriately.

# Push Process
Before pushing you should run `make release`. That will run all of the formatting, linting, testing, and building that will happen in CI. If that fails then you'll know before pushing it off to a branch. You can also reproduce what happens on CI servers using the `act` tool. See the details in the section below. The process in general is

- `make release` to make sure it builds.
- bump the version using `make bump-patch`, `make bump-minor`, `make bump-major`, `make bump-release`, or `make bump-dev`, depending on the magnitude of the change. This will update all files that mention the version number. Commit those changes if they look right or reach out of you're not sure what to do.
- Patch is for small bug fixes.
- Minor is for new features.
- Major is for breaking changes.
- If this is a new feature then add some examples to `examples/`
- Push to a branch on Github.
- Submit a pull request to the main repo.

## Run CI locally with `act`
You can run local github actions on ubuntu using [act](https://github.com/nektos/act). Currently, you need to build the latest docker image for ubuntu using the following dockerfile

```dockerfile
FROM ubuntu:20.04
Expand All @@ -101,65 +108,5 @@ act -P ubuntu-latest=ubuntu-builder
```
It will run all the tests in ubuntu, currently act does not support matrix.os runs on mac-os or windows

## Release process

* If you are doing development locally, use the following command to create a local dev version.

Some basic guideline for choosing whether it's `patch|minor|major`:
* Patch is for small bug fixes
* Minor is for new features
* Major is for breaking changes / API

The flow looks like this:
```
check out master -> create branch -> make changes -> bump dev -> publish dev
-> bump beta -> create merge request -> merge in to master
-> check out master -> bump release -> merge request to release -> merge into release
```

### 1. Local development
Start with a `dev` version locally (and you can publish them as well if needed).

```
cd whylogs-python/
bump2version dev --verbose --dry-run [--allow-dirty]
bump2version dev --verbose
```

### 2. Pushing to master branch

* If you are planning to push to `master` branch, please first create a dev version (see the above guide).
**You'll have to bump it to a `beta` version or the build will fail**. You'll need to do this before creating the merge request:
```
bump2version beta --verbose --dry-run
bump2version beta --verbose
```

### Updating notebooks
Before committing any changes to the example notebooks, you should clear all cell outputs.
We don't want to version control the notebook cell outputs.


### 3. Full release

For full release, you'll have to bump it to a release version and push to `release` branch. This branch
will contain only 'nice-looking' version string (i.e. `1.0.1`). Doing otherwise will fail the build when merging into `release` branch.
```
bump2version release --verbose --dry-run
bump2version release --verbose
```

## Documentation
Auto-generated documentation is handled with [sphinx](https://www.sphinx-doc.org/en/master/).
See the `docs/` folder for more and refer to [docs/README.md](docs/README.md)

### Examples

Example scripts which help demonstrate the use of whylogs can be placed under the `examples/` folder.
Refer to [examples/README.md](examples/README.md) for more info


### Doc string format
We use the [numpydocs docstring standard](https://numpydoc.readthedocs.io/en/latest/format.html), which is human-readable
and works with [sphinx](https://www.sphinx-doc.org/en/master/) api documentation generator.

53 changes: 45 additions & 8 deletions Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,28 +5,63 @@ src.python.pyc := $(shell find ./src -type f -name "*.pyc")
src.proto.dir := ./proto/src
src.proto := $(shell find $(src.proto.dir) -type f -name "*.proto")

version := 0.4.5-dev1

dist.dir := dist
egg.dir := .eggs
build.dir := build
# This isn't exactly true but its the only thing that we easily know the name of at this point. Its a good proxy for
# the wheel since its created along with it.
build.wheel := $(dist.dir)/whylogs-0.4.5.dev1.tar.gz
build.wheel := $(dist.dir)/whylogs-$(version).tar.gz
build.proto.dir := src/whylogs/proto
build.proto := $(patsubst $(src.proto.dir)/%.proto,$(build.proto.dir)/%_pb2.py,$(src.proto))

default: dist

release: format lint test dist ## Compile distribution files and run all tests and checks.

.PHONY: dist clean clean-test help format lint test install coverage docs default proto test-notebooks github release test-system-python format-fix
.PHONY: dist clean clean-test help format lint test install coverage docs default proto test-notebooks github release
.PHONY: test-system-python format-fix bump-patch bump-minor bump-major publish bump-dev bump-build bump-release blackd

ifeq (, $(shell which poetry))
ifeq ($(shell which poetry), )
$(error "Can't find poetry on the path. Install it at https://python-poetry.org/docs.")
endif

help:
@python -c "$$PRINT_HELP_PYSCRIPT" < $(MAKEFILE_LIST)

bump-patch: ## Bump the patch version (_._.X) everywhere it appears in the project
@$(call i, Bumping the patch number)
bumpversion patch --allow-dirty

bump-minor: ## Bump the minor version (_.X._) everywhere it appears in the project
@$(call i, Bumping the minor number)
bumpversion patch --allow-dirty

bump-major: ## Bump the major version (X._._) everywhere it appears in the project
@$(call i, Bumping the major number)
bumpversion patch --allow-dirty

bump-release: ## Convert the version into a release variant (_._._) everywhere it appears in the project
@$(call i, Bumping the major number)
bumpversion release --allow-dirty

bump-dev: ## Convert the version into a dev variant (_._._-dev__) everywhere it appears in the project
@$(call i, Bumping the major number)
bumpversion dev --allow-dirty

bump-build: ## Bump the build number (_._._-____XX) everywhere it appears in the project
@$(call i, Bumping the major number)
bumpversion build --allow-dirty

publish: clean dist ## Clean the project, generate new distribution files and publish them to pypi
@$(call i, Publishing the currently built dist to pypi)
poetry publish

blackd:
@$(call i, Running the black server)
poetry run blackd

clean: clean-test ## Remove all build artifacts
rm -f docs/whylogs.rst
rm -f docs/modules.rst
Expand Down Expand Up @@ -72,13 +107,15 @@ lint-fix: ## automatically fix linting issues
poetry run autoflake --in-place --remove-unused-variables $(src.python) $(tst.python) $(tst.notebooks.python)

format: ## Check formatting with black
@$(call i, Checking formatting)
@$(call i, Checking import formatting)
poetry run isort --check-only .
@$(call i, Checking code formatting)
poetry run black --check .

format-fix: ## Fix formatting with black. This updates files.
@$(call i, Formatting code)
@$(call i, Formatting imports)
poetry run isort .
@$(call i, Formatting code)
poetry run black .

test: dist ## run tests with pytest
Expand Down Expand Up @@ -133,18 +170,18 @@ export PRINT_HELP_PYSCRIPT

define i
echo
echo "[INFO] $1"
python scripts/colors.py INFO "$1"
echo
endef

define w
echo
echo "[WARN] $1"
python scripts/colors.py WARN "$1"
echo
endef

define e
echo
echo "[ERROR] $1"
python scripts/colors.py ERROR "$1"
echo
endef

0 comments on commit 5e0a5dc

Please sign in to comment.