The staging

1. DescribeExport every candidate field’s metadata to the repo. This is the rollback.
2. HideRemove from layouts and field-level security. Two weeks’ wait — anything that breaks now breaks loudly and reversibly.
3. FreezeRename with a ZZZ_DEPRECATED_ prefix. Two more weeks. Formulas and integrations that reference it by API name keep working; humans notice the label.
4. DeleteIn batches of twenty, one object at a time, with the recycle bin’s fifteen-day window as the final net.

The one that came back

Day nine of the hide stage: a regional team’s quarterly forecast broke. The field had zero values in twelve months — because they populated it during one week per quarter, and the audit window had landed between weeks. Test one had lied, politely.

The fix took ten minutes because hiding is reversible. Had we deleted on day one, it would have been a restore-from-describe, a data reload, and a meeting with names in it. The staged process is slower by design: every stage before the last one is a question, and only the last one is an answer.

The result

177 fields gone, one reinstated, zero incidents that survived a fortnight. The org’s setup pages load noticeably faster, which nobody predicted and everybody mentions.

What “unused” actually means

A field is a candidate for deletion only when all four are true:

1. No recent values. SELECT COUNT() WHERE Field__c != null AND LastModifiedDate = LAST_N_DAYS:365 is zero or near it.
2. No metadata references. The dependency API knows about formulas, Flows and layouts; it does not know about report filters, so those are a separate pass.
3. No integration touches it. The field-level “where is this mapped” question no tool answers — this is the week of the project, and it is mostly reading integration configs and asking people.
4. Nobody claims it. A field with zero data can still be the one field the CFO’s one report groups by, once a year, in January.

The spreadsheet

One row per custom field, four columns for the four tests, and a fifth for the owner’s sign-off. Ours had 214 rows and took three weeks of background effort. 178 passed all four tests — which is the number that makes part two worth doing.

Chapters

• 0:00 — What we are building, and why the shared sandbox had to go
• 1:12 — The Dev Hub auth URL, and where the newline hides
• 3:45 — The workflow file, line by line
• 7:30 — First red run, and reading the Actions log
• 9:58 — Green, and what it costs per PR

The checklist itself

A deployment that goes well is boring, and the boredom is manufactured in the week before:

1. The validation ran yesterday, not this morning — a validation that just passed is a validation that had no time to rot.
2. The permission-set assignment is in the runbook, because deployed and visible are different states.
3. The rollback is written down before it is needed, when everyone is calm and nobody needs it.
4. Someone who did not build it reads the steps aloud — the step that cannot be read aloud is the step that was never actually written.

The part people skip

Item four. It costs fifteen minutes and it has caught something every single time we have done it, which says less about the checklist and more about how deployment plans get written: by the person who no longer sees the missing step because they have done it by hand forty times.

So the reflex is defensive. You learn the numbers, you keep under them, and you think of the limits as a tax on getting work done.

That reflex is wrong, and it is expensive. The limits are not a tax. They are the platform stating, in numbers, what shape multi-tenant code has to be.

The limits describe a shape

Look at the three that bite most often:

Every one of them is the same instruction wearing a different hat: work in sets, not in loops. That is not a Salesforce rule. It is the rule for any system where the database is over a network and the CPU is shared.

What that looks like

The version that fails is the one everybody writes first:

// Wrong: one query per record. Works on 1 record, dies on 201.
for (Account a : Trigger.new) {
    List<Contact> kids = [SELECT Id FROM Contact WHERE AccountId = :a.Id];
    if (kids.isEmpty()) {
        a.addError('Every account needs a contact.');
    }
}

The version that passes is not more complicated. It is the same logic with the query lifted out:

// Right: one query, whatever the batch size.
Map<Id, Account> byId = new Map<Id, Account>(Trigger.new);

Set<Id> withContacts = new Set<Id>();
for (Contact c : [SELECT AccountId FROM Contact WHERE AccountId IN :byId.keySet()]) {
    withContacts.add(c.AccountId);
}

for (Account a : Trigger.new) {
    if (!withContacts.contains(a.Id)) {
        a.addError('Every account needs a contact.');
    }
}

Two loops instead of one, and a set in between. It is longer. It is also the version that does not care whether it is handed one record or two hundred, which is the only property that matters in a trigger.

Read them forwards

Once you stop reading limits as obstacles, they start answering design questions before you have to ask them.

• Heap is 6 MB. So a job that has to touch a million records is Batch Apex, and you knew that before you wrote a line.
• CPU time is 10 seconds. So the formula field that recalculates a rollup across a hierarchy is not going in a trigger.
• Callouts are limited to 100, and none after DML. So the integration is asynchronous, and you knew that before the first design meeting.

Each of those is a decision the platform has already made. Arguing with it costs a sprint; reading it costs an afternoon.

The one exception

None of this makes the limits comfortable. The 10-second CPU limit in particular punishes code that is correct but naive, and the error it throws tells you nothing about which line was slow.

But that is a complaint about the diagnostics, not about the constraint. The constraint is doing its job: it is stopping you from writing something that would have fallen over in production anyway, six months later, when the data volume caught up with you.

Better to find out in the sandbox.

The argument

Every org contains a field called something like Amount2__c, and every Amount2__c tells the same story: someone needed a second amount, the first one was taken, and the deadline won. The name is a confession that the data model stopped being designed at some point and started being appended to.

Names are the cheapest architecture there is. Three rules cover most of it:

• Name the meaning, not the mechanics. Renewal_Amount__c, not Amount2__c; Is_Billing_Synced__c, not Flag3__c.
• Put the unit in the name when the type does not carry it — Term_Months__c has prevented more bugs than most validation rules.
• A prefix is a namespace. INT_ for integration-owned fields tells an admin “changing this breaks something you cannot see” at a glance, which is the entire job of a naming convention: making danger legible.

The uncomfortable corollary

You cannot rename your way out of a bad model — a field named beautifully for the wrong concept is worse than an ugly one, because it looks deliberate. Naming is the finish, not the structure; the structure is the field audit.

Dear org 00D4x0000012345,

I am sorry about the trigger. All four of them, on Account, each written in a different year by a different version of me, each convinced it was the last one anyone would need. I know now why the platform people talk about one trigger per object the way they do — they had met me before I arrived.

I am sorry about Amount2__c. You know what you did, and so do I.

Thank you for the governor limits. I called them many things in 2017, none printable, all wrong. They were the only code review I had that year — the only voice in the building saying this will not scale to someone who did not yet know the word “scale” could apply to him.

You taught me that every org is an archaeology site, that every weird field had a reasonable Tuesday behind it, and that the person whose mess I was cursing was usually me with less sleep. I have cursed gently ever since, in your honour.

The new org says hello. It has one trigger per object. You would hate it.

— A.

It took eleven weeks. Here is what worked.

Do not start with the hard one

The instinct is to prove the approach on the worst component — if the gnarliest one converts, the rest are easy. That instinct produces three weeks of work with nothing shipped and a team that has stopped believing the project will finish.

Start with the most boring one instead. Ours was a badge that displayed a case status. Two hours, shipped the same day, and suddenly the migration was a thing that happened rather than a thing that was planned.

The order that worked

1. Leaf components firstAnything with no children and no events. Roughly half the list, and each one is an afternoon.
2. Then shared utilitiesThe date formatter, the toast wrapper, the field-level-security check. Convert once, and every later component gets easier.
3. Then containers, bottom-upA container can hold LWC children while it is still Aura. The reverse is not true — which is what dictates the whole order.
4. The application event bus lastIt was the only genuinely hard piece, and by then it was the only piece left.

That third point is the whole strategy. Aura can contain LWC. LWC cannot contain Aura. Every migration order that ignores that fact ends up with a component that cannot be converted until its parent is, and a parent that cannot be converted until its children are.

What it cost

Thirty-eight, not forty-one: three components turned out to be doing something the platform now does natively, and the migration was the first time anyone had looked at them closely enough to notice. That is a real and under-advertised benefit of this kind of work.

What I would do differently

Convert the event bus third, not last. We spent the final fortnight with a compatibility shim translating application events in both directions, and every bug in that period turned out to be the shim. Doing it early would have meant a harder week three and a much calmer week ten.

After: every pull request spins up its own scratch org, deploys into it, runs the full test suite, and destroys the org when the PR closes. Nobody blocks anybody.

The workflow

name: Validate PR
on: [pull_request]

jobs:
  scratch:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install the CLI
        run: npm install --global @salesforce/cli

      # The Dev Hub auth URL lives in a repository secret. It is the only
      # credential in the whole pipeline, and it never touches the log.
      - name: Authenticate to the Dev Hub
        run: |
          echo "$" > auth.txt
          sf org login sfdx-url --sfdx-url-file auth.txt --set-default-dev-hub
          rm auth.txt

      - name: Create the scratch org
        run: sf org create scratch -f config/project-scratch-def.json -a ci -d 1 -y 1

      - name: Push and test
        run: |
          sf project deploy start -o ci
          sf apex run test -o ci --code-coverage --result-format human --wait 20

      # `always()` matters: without it a failed test leaves the org alive and
      # the daily scratch-org limit is gone by Thursday.
      - name: Delete the scratch org
        if: always()
        run: sf org delete scratch -o ci --no-prompt

The parts that are not obvious

Scratch org limits are the real constraint. A Dev Hub has a daily and an active allocation, and a busy repository will hit both. Setting the duration to one day rather than the default seven is most of the fix; the always() cleanup step is the rest.

Test data has to come from somewhere. A scratch org is genuinely empty. Either every test builds its own data with a factory, or you maintain a seed plan under data/. We started with the seed plan, then moved to factories because the plan drifted from the schema and nobody noticed until it broke.

It is slower than you want. Ours takes eleven minutes end to end, most of it org creation. That is fine for a PR gate and useless as an inner-loop tool — developers still work in a long-lived personal scratch org and only feel this when they push.

Was it worth it

Two days to build, and release-day deployment failures went from routine to rare. The number I did not expect: the review queue moved faster, because a reviewer who can see a green run on a real org spends less time reading the diff for deployment problems and more time reading it for actual problems.

It worked. It also meant an average of eight minutes between “the deal closed” and “billing knows”, a query that got slower every quarter, and 96 API calls a day spent mostly discovering that nothing had happened.

What we changed

A Platform Event published from the trigger, and a subscriber on the other side.

// The event is a fact about the past, not a command. Named accordingly —
// OpportunityClosed, not CloseOpportunity — because a subscriber that reads
// it as an instruction will eventually do something we did not ask for.
List<Opportunity_Closed__e> events = new List<Opportunity_Closed__e>();

for (Opportunity o : Trigger.new) {
    Opportunity old = Trigger.oldMap.get(o.Id);
    if (o.IsWon && !old.IsWon) {
        events.add(new Opportunity_Closed__e(
            Opportunity_Id__c = o.Id,
            Amount__c         = o.Amount,
            Closed_At__c      = System.now()
        ));
    }
}

// publish() returns a result per event and does NOT throw. Ignoring the
// return value is the single most common way to lose an event silently.
for (Database.SaveResult sr : EventBus.publish(events)) {
    if (!sr.isSuccess()) {
        Logger.error('Failed to publish OpportunityClosed', sr.getErrors());
    }
}

The four things worth knowing

Publishing is not transactional in the way you expect. With the default PublishAfterCommit behaviour, the event goes out only if the transaction commits — which is what you want. With PublishImmediately, it goes out even if the transaction rolls back, and you have told a downstream system about something that did not happen.

Delivery is at-least-once. A subscriber will occasionally see the same event twice. Every handler needs to be idempotent, and the cheapest way to get there is a unique external id on whatever the subscriber writes.

The event bus retains for 72 hours. That is your entire replay window. A subscriber that is down over a long weekend does not catch up.

High-volume events have their own allocation, and it is consumed by delivery, not by publication. One event delivered to four subscribers is four against the limit.

The numbers

The API graph flattening was the part that got the change approved. The latency was the part that mattered.