tCMS/CLAUDE.md

CLAUDE.md

This file is the procedure for work in this repository. The POD and the files named below say what the code is and how it is written.

tCMS is a CMS for perl, run by tPSGI, in which a post can be content of any type. Read design.md first: it says what a post is, why the routing table is data, and where a given change belongs.

Read the code before you change it

Before you answer a question about the code here, look for something in it, or edit it, invoke perl-slop:reading-perl.

Most of the code here is older than the conversation about it. A line that looks pointless is usually the scar of something that went wrong once. The reason is in the commit, not in the file. So read before the first edit, not after the tests fail.

The same pass asks whether the code that you want to write is already here, under a name that you did not search for. Two subs that do one job are a defect, whichever one is better.

What perl this runs on

Every module, script and test says use 5.040, and MIN_PERL_VERSION in Makefile.PL says the same. .perlcriticrc depends on it. The header of that file names the policies that this version of perl makes unnecessary. So if you raise or lower the floor, change the profile as well as the use lines.

Where it is written down

Readme.md	what tCMS is for, and how to deploy it
design.md	the architecture, and where a given change belongs
.perlcriticrc	the policies, which are the house style made enforceable
CHANGELOG	what changed, per major version
Makefile.PL	what has to be installed to run tCMS, and to develop it
Installer.mk	the directories and the front-end files that an install needs

Finishing a changeset

Before you commit, apply these skills in this order:

1. perl-slop:data-perl: make sure that the data is defined, coerced, validated and scoped in the way that perl expects.
2. perl-slop:testing-perl: make sure that each behavior that you added or changed has a test, and that the test is the right kind.
3. perl-slop:reviewing-perl: read the whole diff back against it. This pass finds a second copy of something that the library already does. It also finds a call out to the shell, and a comment that belongs in the commit message.

Then run podchecker on each changed file. Run perl -Ilib -c on each changed script that no test loads, because the tests do not compile it.

The pre-commit hook does the rest. It tidies the Perl that you staged, runs perlcritic on it, and runs the tests that the commit can break, which tests-covering chooses. The post-commit hook keeps the records of tests-covering up to date, in the background. If a step fails, the hook stops the commit and prints the reason. Do not run perltidy or perlcritic yourself, and do not run the tests to decide whether a change is ready to commit.

The hook names each test that failed. Its output does not say why. If a test fails, run that file yourself with -v, and read the output:

prove -lv t/<file>.t

Do the same to see a new test fail before you fix what it tests.

In each clone that you commit from, install both hooks once. Git does not install them for you, and without the hooks the tree drifts from its style:

cp git-hooks/pre-commit git-hooks/post-commit .git/hooks/

A file that no test loads, such as a fixture, gets its tests from .tests-covering-map.pl. A path that the map cannot place runs every test. If a commit runs every test but does not touch everything, the map probably needs a rule. Add the rule in the same change, and name the tests that read the file.

When something is slow

Use perl-slop:profiling-perl. Measure before you conclude anything, and measure again after a change. "It is just slow" is not a finding. A line number and a percentage is a finding.

Installing what development needs

The hooks and .perlcriticrc need the develop prerequisites in Makefile.PL. When .perlcriticrc names a policy from another distribution, add that distribution there in the same change.

cpanm --installdeps --with-develop .

Commits and pull requests

Make a branch. Do not commit to the default branch.

A commit message here says what was wrong and why the change fixes it. Write it in prose and in the imperative mood. Name the behavior, not the diff, for example "Ask the pool whether it takes O_DIRECT, rather than guessing from its name". The message has a job. perl-slop:reading-perl describes a person who finds your line with git blame two years from now. The message is the only thing that can still tell that person why. For the same reason, the why goes in the message and not in a comment.

After you make sure that something works, say what you ran and what it said. A claim that the tests pass needs the line that shows them passing. A claim about your own work needs its evidence too, such as the URL from gh pr create or the sha from git push. A PR number that nobody can open is worse than no number.

If the code of a branch depends on another branch, stack it on that branch. If only a test of it depends on the other branch, do not stack it. A change whose tests need a fix from somebody else is still an independent change. Open it against the default branch, and say in the description what must merge first. A stacked branch merges into its base, whatever that base is. If the base reached the default branch by another route, the stacked change reaches nowhere, and nothing says so.