Migration Engine Design Spec Memo
2026-07-19 JST

This memo records the decisions reached through a review with
ChatGPT ("KSPHP Plus Design Review: Migration & Maintainability")
and the subsequent discussion with Motoi(gikonekos). Implementation
(the migrate.php file itself) had not yet begun at the time of
writing.


1. Project goal
------------------------------------------------------------
Safely migrate old PHP5-era bulletin boards to PHP8, keeping small
communities alive. This is not mere compatibility work -- it's a
community-continuity support project.


2. Top-priority principles
------------------------------------------------------------
* Fast, light, reliable
* Maximize benefit to the operator/users
* Non-destructive maintenance (no refactoring-for-its-own-sake
  changes, respect the original designer's intent, never change
  something just because it "looks cleaner," runtime compatibility
  comes first)
* New behavior must back up the old behavior rather than destroy it
  (2026-07-19, top-priority configuration specified by
  Motoi(gikonekos))
* Users should be able to update safely without doing anything
  themselves (the core philosophy is automatic migration, not a
  manual-installer assumption)


3. File-structure decision (2026-07-19)
------------------------------------------------------------
The Migration Engine will not be built into bbs.php itself; it will
be a separate, standalone file (e.g. migrate.php).

  Reason 1: Building it into bbs.php would mean every single request
  tries to "look for old files and create a backup," which violates
  the "fast, light" principle.

  Reason 2: bbs.php itself is a file that gets distributed and
  overwritten on copy; mixing migration logic into it risks it being
  unintentionally overwritten during a copy. A standalone file avoids
  this risk.

It will be invoked automatically from bbs.php. On first launch only,
the equivalent of migrate.php's processing is required and run
automatically; once detection/migration of the old layout is
complete, it is skipped on every subsequent run (based on the
principle that "the user shouldn't have to do anything" -- this is
designed as an automatic migration engine, not as a manual-run
install.php-style tool).


4. Directory structure
------------------------------------------------------------
Moving toward separating responsibilities into data/, logs/, and
config/ (adopting ChatGPT's review proposal). Each directory ships
with a standard .htaccess that blocks direct external access
(secure by default).


5. Backup method (decided 2026-07-19)
------------------------------------------------------------
Old data is evacuated every time migration runs, but to avoid
overwrite collisions from same-named files, each run is stored in
its own individual folder (a folder-separation approach was adopted
rather than a renaming approach). The original folder structure is
preserved as-is within each folder.

  Example: the old layout's folder structure is copied verbatim
  under backup/YYYY-MM-DD-NN/.

Original files are not deleted until migration success is confirmed.
If a problem occurs, the system stays in a state where it can be
restored immediately from the corresponding backup folder.


6. CSS (already handled)
------------------------------------------------------------
Already handled via css.php. The common CSS that used to live inside
<style> has been externalized, with a structure that dynamically
injects the personal-settings color scheme via the "?c=" parameter.
Confirmed on 2026-07-19 that this matches ChatGPT's review proposal
in terms of separating HTML from design.


7. Admin path
------------------------------------------------------------
Moving toward separating it out of conf.php. Placement outside the
public web root is recommended where possible; where that's
difficult, protect it with config/.htaccess.


8. Database (not adopted, confirmed 2026-07-19)
------------------------------------------------------------
Not adopted for the core system. KSPHP Plus keeps its "lightweight,"
"FTP-deployable," "for small communities" character. Use cases like
full-text search will be handled by a separate project or an export
feature instead.


9. Undecided / future discussion items
------------------------------------------------------------
* The concrete placement method for the config/ admin path (carried
  over to a later stage, not addressed this round)
* Implementation of migrate.php itself -> done as of 2026-07-19 (see
  "Status" at the end of this memo)


10. Final decision on migration scope (2026-07-19)
------------------------------------------------------------
The following are explicitly excluded from migration (no backup
either -- they continue to be used at their current paths as-is).

* upload/ (image uploads): image data is large, and the backup cost
  is too heavy, so it's out of scope.
* archive/ (past-log zips, conf.php's ZIPDIR): likewise can grow
  large, so it's out of scope.

On the other hand, the following are text-based, lightweight, and
cheap to back up, so they remain in scope for migration (unchanged
from the current implementation).

* bbs.log / log/ (logs)
* bbs.cnt / count/ (counter)
* gikoneko_kotoba.dat (Gikoneko fortune-message data)


11. Status (as of 2026-07-19)
------------------------------------------------------------
* migrate.php itself: implemented and verified working
* conf.php: LOGFILENAME/OLDLOGFILEDIR/COUNTFILE/CNTFILENAME rewritten
  to the new-layout paths (other settings in the live conf.php are
  preserved)
* bbs.php: the ksphp_migrate() call on startup has been wired in
* gikoneko.php/gikonekoadd.php: default data path changed to data/
* Remaining task: final review and packaging for release (pending
  go-ahead)


10. Development structure
------------------------------------------------------------
* An official maintainer exists on GitHub (Kaguya and others handle
  official maintenance)
* Motoi(gikonekos): design, improvements, and verification from
  outside the official channel, also credited
* Claude: implementation
* ChatGPT: design review, maintainability, and future-design input
