Source code lives under
src/aw_import_ical/
, with the primary entry point in
cli.py
and the package exposed via
python -m aw_import_ical
or the
aw-import-ical
console script. Supporting utilities such as virtualenv helpers and lint scripts reside in
scripts/
. Documentation belongs in
docs/
; contributor guides sit in
docs/developer/
, and task-scoped logs must be stored in
docs/updates/
. Create a
tests/
directory at the repository root when adding automated checks so the suite mirrors ActivityWatch conventions.
python3 -m venv .venv && source .venv/bin/activate
— spin up a local environment (or run USE_UV=1 python scripts/setup_venv.py
to delegate to uv
).pip install -e ".[dev]"
— install runtime code plus developer extras such as black
and mypy
.python -m aw_import_ical mycalendar.ics --mode replace --aw-port 5600
— execute an import; swap --url
for remote calendars or --mode sync
for diffing.python scripts/typecheck.py
— run the project type-checker; keeps parity with CI expectations once configured.
Use Python 3.7+ syntax, 4-space indentation, and descriptive
snake_case
identifiers. Keep functions focused, prefer dependency injection for network clients, and add PEP 257 docstrings to public entry points. Format code with
black
(configured via the dev extra) and run
mypy
before opening a pull request. Configuration files should stay lowercase with hyphenated or underscored names.
Adopt
pytest
for new tests and follow the repository rule of storing them beside the code or under
tests/
. Name files
test_<module>.py
and ensure fixtures produce synthetic
.ics
data free of personal information. Target balanced coverage across recurrence handling, bucket reconciliation, and auth fallbacks; record metrics via
pytest --cov
once coverage tooling lands. Update
docs/updates/
whenever the suite grows or coverage expectations change.
Use Conventional Commit syntax (
type(scope): subject
), keeping subjects imperative and under 72 characters, with bodies explaining the motivation and risk. Reference related ActivityWatch issues using “Refs #123” or “Fixes #123”. Pull requests should summarize behavior changes, note manual or automated verification, and attach relevant logs or screenshots. Wait for CI (or documented local equivalents) to pass before requesting review.
Do not commit tokens written to
~/.config/activitywatch/
; rely on environment variables or local files ignored by Git. When working with private calendar data, redacted fixtures belong outside the repository unless explicitly sanitized. Keep
.env
files and OAuth credentials out of version control and document any new configuration knobs in
docs/developer/
.
Load
.agents/rules/
at task start and apply the highest-priority instructions. Keep doc updates inside
docs/
and log task-scoped notes in
docs/updates/
using the repository template. When tests change, follow
testing.md
placement guidance and update the checklist. Note consulted rules in implementation notes or PR descriptions. For complex multi-file work, follow the staged planning flow in
planning.md
and pause for approval before execution.