Project Logging & Changelog¶

Every meaningful operation performed by Odoofly on a project leaves a persistent record inside the project directory. There are two complementary logging systems, each with a different purpose and lifecycle.

The two log files¶

File	Generator	Purpose	Git status
`CHANGELOG.md`	`append_project_changelog()`	Curated history of significant operations, grouped by date and action	Committed (part of the project repo)
`project.log`	`append_project_log()`	High-frequency operational trace with timestamps (start/stop/restart/init/update)	Gitignored (operational, noisy)

Both live at the root of the project directory (the one that contains project.yml).

<project>/
├── project.yml          # IaC manifest
├── CHANGELOG.md         # Curated operation history (committed)
├── project.log          # Timestamped operational log (gitignored)
└── <environment>/       # per-environment data

`CHANGELOG.md` — curated history¶

Written by append_project_changelog(project_path, action, *details), where action is one of:

Added — something was created
Changed — something was modified or reconfigured
Removed — something was deleted

Entries are grouped by date (## YYYY-MM-DD) and by action (### Added). New entries for the same day/action are merged into the existing section. If the file doesn't exist yet, it is created with the standard header.

Example¶

# Project Changelog

Auto-generated by Odoofly CLI operations.

## 2026-08-03

### Added

- Database `staging_odoo` created (env: `main`)
- Staging environment `st_202608031430` created from main
- Database `postgres` copied & neutralized from `odoo` (env: `main`)

### Changed

- Modules updated in `main` (all modules)
- Password changed for user `admin` (db: `odoo`, env: `main`)

### Removed

- Backup `odoo_2026-08-01_09-30-00.zip` deleted (env: `main`)

`project.log` — operational trace¶

Written by append_project_log(project_path, action, *details). One line per entry, always timestamped:

2026-08-03 10:15:22 [UPDATED] Environment `main` module all updated
2026-08-03 10:17:05 [INITIALIZED] Environment `main` initialized
2026-08-03 10:18:00 [FAILED] Environment `staging` initialization failed
2026-08-03 10:19:12 [STARTED] Environment `main` up
2026-08-03 10:20:47 [STOPPED] Environment `main` down
2026-08-03 10:21:30 [RESTARTED] Environment `main` restarted
2026-08-03 10:22:05 [CHANGED] Password changed for user `admin` (db: `odoo`, env: `main`)

Because it is gitignored, it is safe to write frequently — this is where the container lifecycle lives (env up, env down, env restart). CHANGELOG.md is reserved for operations you want to keep in version control and show to collaborators.

Reference: where each operation logs¶

Legend — CL: CHANGELOG.md · PL: project.log

Operation	Command	CL	CL action	PL
Project created	`of project new`	✓	Added
Project initialized	`of project init`	✓	Changed
Environment created	`of env new`	✓	Added
Environment initialized	`of env init`	✓	Changed	✓
Environment removed	`of env rm`	✓	Removed
Environment up / down / restart	`of env up` · `down` · `restart`			✓
Module installed	`of env install`	✓	Changed
Module uninstalled	`of env uninstall`	✓	Removed
Modules updated	`of env update`	✓	Changed	✓
User password changed	`of env password`	✓	Changed	✓
Server options updated	`of env conf`	✓	Changed
Staging created	`of env staging new`	✓	Added
Staging refreshed	`of env staging refresh`	✓	Changed
Backup created	`of env backup new`	✓	Changed
Backup restored	`of env restore`	✓	Changed
Backup deleted	`of env backup rm`	✓	Removed
Backups pruned	`of env backup prune`	✓	Removed
Database created	`of db create`	✓	Added
Database dropped	`of db rm`	✓	Removed
Database copied & neutralized	`of db cpn`	✓	Added
Repository added	`of repo add`	✓	Added
Repository removed	`of repo rm`	✓	Removed
Tokens updated	`of repo auth`	✓	Changed

Detailed messages¶

Operation	Action	Logged message
Project initialized	Changed	`Project \`` initialized`+ one line`Environment `` initialized` per environment
Environment initialized	Changed	`Environment \`` initialized`
Module installed	Changed	`Module \`` installed in DB `` (env: ``)`
Module uninstalled	Removed	`Module \`` uninstalled from DB `` (env: ``)`
Modules updated	Changed	`Modules updated in \`` (module `` \| all modules)`/`Environment `` updated (git) [module ``]`
Password changed	Changed	`Password changed for user \`` (db: ``, env: ``)`
Staging created	Added	`Staging environment \`` created from main`
Staging refreshed	Changed	`Staging \`` refreshed from ```
Backup created	Changed	`Backup \`.zip` created for environment ```
Backup restored	Changed	`Backup restored from \`.zip` to environment ```
Backup deleted	Removed	`Backup \`.zip` deleted (env: ``)`
Backups pruned	Removed	`Deleted <n> backup(s) (env: \``)` (only when ≥ 1 deleted)
Database created	Added	`Database \`` created (env: ``)`
Database dropped	Removed	`Database \`` dropped (env: ``)`
DB copied & neutralized	Added	`Database \`` copied & neutralized from `` (env: ``)`

Operations that do NOT log¶

The following are intentionally excluded:

Read-only commands (env ls, env status, env url, db ls, repo ls, backup ls, project check, env check, env modules, env users, env stats) — they don't modify anything.
Interactive / debug shells (env shell, db shell) — no lasting effect.
Container lifecycle (env up, env down, env restart) — logged only to project.log to avoid noise in the curated changelog.

Security notes¶

The password itself is never written to any log. of env password only records that the password changed, for which user, database and environment.
Repository tokens are resolved from ${VAR} placeholders and stored in .env; no token value is ever logged.
project.log is gitignored because it may contain operational detail. CHANGELOG.md should be reviewed before committing — it is part of the project repo by design.

Technical behavior¶

append_project_changelog silently does nothing if the project path does not exist (safe to call from any command).
Entries for the current day and action are inserted into the existing section; the file is created if missing.
append_project_log always appends a line with format YYYY-MM-DD HH:MM:SS [ACTION] detail and creates project.log if missing.
Both functions are idempotent per call: each invocation writes one entry (no de-duplication, matching the project's operation-counting convention).

Automation & CI¶

Both files can be consumed in scripts:

# Last 5 changelog entries
git -C "$PROJECT_DIR" log --oneline -- CHANGELOG.md -5

# Newest operation recorded today
grep "^## $(date +%F)" "$PROJECT_DIR/CHANGELOG.md"

# Last restore operation
grep -i "restore" "$PROJECT_DIR/CHANGELOG.md" | tail -1

# Last 10 operational lines
tail -10 "$PROJECT_DIR/project.log"