Add development instructions to README.md

README.md

@@ -1,3 +1,65 @@
-# New project template
+# FawltyDeps
 
-Use this template when creating a new project.
+A dependency checker for Python.
+
+Find undeclared 3rd-party dependencies in your Python project.
+
+# Installation
+
+TODO: Fill when released in PyPI
+
+# Usage
+
+To check the project in the current directory run:
+
+```
+fawltydeps
+```
+
+Options available:
+
+```
+> fawltydeps --help
+usage: fawltydeps [-h] [--code CODE] [-v] [-q]
+
+Find undeclared 3rd-party dependencies in your Python project.
+
+options:
+  -h, --help     show this help message and exit
+  --code CODE    Code to parse for import statements (file or directory, use '-' to read code from stdin; defaults to the current directory)
+  -v, --verbose  Increase log level (WARNING by default, -v: INFO, -vv: DEBUG)
+  -q, --quiet    Decrease log level (WARNING by default, -q: ERROR, -qq: FATAL)
+```
+
+# Documentation
+
+TODO: Add design doc
+
+[Code design](./docs/CodeDesign.md)
+
+# Development
+
+The project uses [Poetry](https://python-poetry.org/). Install Poetry, and run:
+
+```
+poetry shell
+```
+
+To install the project run:
+
+```
+poetry install
+```
+
+Inside the shell you have a Python virtual environment with all dependencies declared in pyproject.toml installed.
+To test, typecheck and ensure code formatting you just run:
+
+```
+pytest          # tests
+mypy            # type annotations checks
+black --check   # formater checks
+pylint          # linter
+isort           # import sort
+```
+
+TODO: explain how to run CI locally when [#15](https://github.com/tweag/FawltyDeps/issues/15) is completed

docs/CodeDesign.md

@@ -0,0 +1,24 @@
+# Code design
+
+We value composability and functional style.
+We want the code to be readable, testable and maintainable. That is why we use:
+
+- code formatter `black` to unify the code style,
+- `pylint` and `isort` for linting
+- `mypy` for typecheck
+- `pytest` for testing
+  to ensure this quality.
+
+The code must be type-annotated and functions should have docstrings.
+
+FawltyDeps searches for imports and dependencies and to do it efficiently, generators are used.
+
+## Tests
+
+We do not aim for 100% coverage but to document the usecases via tests. FawltyDeps has unit and integration tests.
+
+Tests have following naming convention:
+
+```
+test_{tested_function}__{short_description}__{expected_result}
+```