jazzband · jmaupetit · Dec 14, 2025 · Dec 14, 2025
diff --git a/.python-version b/.python-version
@@ -0,0 +1 @@
+3.12
diff --git a/.travis.yml b/.travis.yml
diff --git a/Makefile b/Makefile
@@ -1,57 +1,39 @@
-# Watson
+# -- General
+SHELL := /bin/bash
 
-PYTHON ?= python
-PIP ?= pip
+# ==============================================================================
+# RULES
 
-VENV = virtualenv
-VENV_ARGS = -p $(PYTHON)
-VENV_DIR = $(CURDIR)/.venv
-VENV_WATSON_DIR = $(CURDIR)/data
+default: help
 
-all: install
+# -- Build
+bootstrap: ## bootstrap the project for development
+bootstrap: \
+  build
+.PHONY: bootstrap
 
-$(VENV_DIR): requirements-dev.txt
-	$(VENV) $(VENV_ARGS) "$(VENV_DIR)"
-	echo "export WATSON_DIR=\"$(VENV_WATSON_DIR)\"" >> "$(VENV_DIR)"/bin/activate
-	echo "set -x WATSON_DIR \"$(VENV_WATSON_DIR)\"" >> "$(VENV_DIR)"/bin/activate.fish
-	"$(VENV_DIR)"/bin/pip install -U setuptools wheel pip
-	"$(VENV_DIR)"/bin/pip install -Ur $<
+build: ## install project
+	uv sync --locked --all-extras --dev
+.PHONY: build
 
-.PHONY: env
-env: $(VENV_DIR)
+docs-serve: ## run documentation server 
+	uv run mkdocs serve -w docs
+.PHONY: docs-serve
 
-.PHONY: install
-install:
-	$(PYTHON) setup.py install
+docs-publish: ## publish documentation
+	uv run mkdocs gh-deploy --force
+.PHONY: docs-publish
 
-.PHONY: install-dev
-install-dev:
-	$(PIP) install -r requirements-dev.txt
-	$(PYTHON) setup.py develop
+test: ## run tests
+	uv run pytest
+.PHONY: test
 
-.PHONY: check
-check: clean
-	$(PYTHON) setup.py test
-
-.PHONY: clean
-clean:
-	find . -name '*.pyc' -delete
-	find . -name '__pycache__' -type d | xargs rm -fr
-
-.PHONY: distclean
-distclean: clean
-	rm -fr *.egg *.egg-info/ .eggs/
-
-.PHONY:
-mostlyclean: clean distclean
-	rm -rf "$(VENV_DIR)"
-
-.PHONY: docs
-docs: install-dev
-	$(PYTHON) scripts/gen-cli-docs.py
-	mkdocs build
-
-.PHONY: completion-scripts
 completion-scripts:
 	scripts/create-completion-script.sh bash
 	scripts/create-completion-script.sh zsh
+.PHONY: completion-scripts
+
+# -- Misc
+help:
+	@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
+.PHONY: help
diff --git a/README.md b/README.md
@@ -0,0 +1,94 @@
+![Watson Logo](https://jazzband.github.io/Watson/img/logo-watson.svg)
+
+![PyPI - Version](https://img.shields.io/pypi/v/td-watson)
+
+Watson is here to help you manage your time. You want to know how much time you
+are spending on your projects? You want to generate a nice report for your
+client? Watson is here for you.
+
+Wanna know what it looks like? Check this below.
+
+[
+![](https://jazzband.github.io/Watson/img/watson-demo.gif)
+](https://asciinema.org/a/35918)
+
+Nice isn't it?
+
+## Quick start
+
+### Installation
+
+The easiest way to install Watson is to use [uv](https://docs.astral.sh/uv/):
+
+```sh
+$ uv tool install td-watson
+```
+
+This will create a Python virtual environment for Watson and a shortcut
+available in your `$PATH`.
+
+Alternatively, you may use Pip instead (in a virtual environment):
+
+```sh
+$ pip install --user td-watson
+```
+
+On OS X, a [Homebrew](http://brew.sh/) formula is also available:
+
+```sh
+$ brew update && brew install watson
+```
+
+If you need more details about installing watson, please refer to the
+[documentation](https://jazzband.github.io/Watson)
+
+### Usage
+
+Start tracking your activity via:
+
+```sh
+$ watson start world-domination +cats
+```
+
+With this command, you have started a new **frame** for the *world-domination*
+project with the *cats* tag. That's it.
+
+Now stop tracking you world domination plan via:
+
+
+```sh
+$ watson stop
+Project world-domination [cats] started 8 minutes ago (2016.01.27 13:00:28+0100)
+```
+
+You can log your latest working sessions (aka *frames*) thanks to the `log`
+command:
+
+
+```sh
+$ watson log
+Tuesday 26 January 2016 (8m 32s)
+      ffb2a4c  13:00 to 13:08      08m 32s   world-domination  [cats]
+```
+
+Please note that, as [the report
+command](https://tailordev.github.io/Watson/user-guide/commands/#report), the
+`log` command comes with projects, tags and dates filtering.
+
+To list all available commands, either [read the
+documentation](https://tailordev.github.io/Watson) or use:
+
+
+```sh
+$ watson help
+```
+
+## Contributor Code of Conduct
+
+If you want to contribute to this project, please read the project [Contributor
+Code of Conduct](https://tailordev.github.io/Watson/contributing/coc/)
+
+## License
+
+Watson is released under the MIT License. See the bundled LICENSE file for
+details.
diff --git a/README.rst b/README.rst
diff --git a/docs/contributing/hack.md b/docs/contributing/hack.md
@@ -3,41 +3,26 @@
 Ready to contribute? Here's how to set up *Watson* for local development.
 
 ## Python requirements
-* Python (2/3) interpreter installed
-* `pip` tool to install package dependencies
-* `virtualenv` tool to create virtual environments
+
+- Python 3.10+
+- [UV](https://docs.astral.sh/uv/) package manager
 
 ## Get started!
 
-1. Fork the [Watson repository](https://github.com/TailorDev/Watson/) on GitHub.
+1. Fork the [Watson repository](https://github.com/jazzband/Watson/) on GitHub.
 
 2. Clone your fork locally:
 
         $ git clone git@github.com:your_name_here/Watson.git
 
-3. Create a virtual environment:
+3. Create a virtual environment and install project dependencies:
 
         $ cd Watson
-        $ make env
-
-    The Python version used will be the one accessible using the `python`
-    command in your shell.
-
-    To use a different Python version, define the `PYTHON` shell variable.
-    For example:
-
-        $ PYTHON=python3.5 make env
-
-4. Install dependencies and deploy Watson inside the virtual environment:
-
-        $ source .venv/bin/activate
-        (.venv) $ make install-dev
-
-    If you are using fish shell, source `.venv/bin/activate.fish` instead.
+        $ make bootstrap
 
 5. Create a branch for local development:
 
-        (.venv) $ git checkout -b name-of-your-bugfix-or-feature
+        $ git checkout -b name-of-your-bugfix-or-feature
 
     Now you can make your changes locally.
 
@@ -48,7 +33,7 @@ Ready to contribute? Here's how to set up *Watson* for local development.
     - Every time you run `watson` inside the virtual environment, the source
       code inside the `watson/` subfolder will be used.
     - To avoid messing with your real Watson data, watson will use `data/` as
-      the [application folder](../user-guide/configuration/#application-folder)
+      the [application folder](../user-guide/configuration.md/#application-folder)
       inside the virtual environment. You can run `watson projects` to check
       that your real projects are not shown.
 
@@ -58,9 +43,9 @@ Ready to contribute? Here's how to set up *Watson* for local development.
         (.venv) $ tox
 
 7. If you have added a new command or updated/fixed docstrings, please update
-    the documentation:
+    the documentation. You can check changes live using:
 
-        (.venv) $ make docs
+        $ make docs-serve
 
 8. Commit your changes and push your branch to GitHub:
 
@@ -75,14 +60,10 @@ Ready to contribute? Here's how to set up *Watson* for local development.
 ## Run the tests
 
 The tests use [pytest](http://pytest.org/). To run them with the default Python
-interpreter:
-
-    $ py.test -v tests/
+interpreter run:
 
-To run the tests via [tox](http://tox.testrun.org/) with all Python versions
-which are available on your system and are defined in the `tox.ini` file,
-simply run:
+    $ make test 
 
-    $ tox
+If you want to run pytest with custom options, use:
 
-This will also check the source code with [flake8](http://flake8.pycqa.org).
+    $ uv run pytest -x -k test_cli