Skip to main content

Common Maintenance Tasks (Task-Based)

Focus: practical scenarios that often occur. All steps below are assumed to be done in a separate branch + non-production environment first.

1) Add a new field in the API response​

Purpose: add information without destroying the old client.

Changed files:

  • Controller/Resource related endpoint
  • docs/api-reference.md
  • docs/request-response-catalog.md

Safe steps:

  1. Add fields as optional (don't immediately make them mandatory).
  2. Make sure default/null handling is safe.
  3. Add test response schema.
  4. Update endpoint documentation.

Verification:

  • Old endpoints still pass the minimum contract.
  • The old client didn't parse errors.

Rollback risk:

  • If the client has problems, roll back to the previous response.
  • Keep compatibility of at least 1 release version.

2) Fix PO state transition bug​

Purpose: prevent jump states without authorization.

Changed files:

  • Controller/service PO status
  • Role validation rules
  • docs/state-machine.md

Safe steps:

  1. Mapping current state vs target state.
  2. Add guard per role.
  3. Add tests for valid and invalid paths.

Verification:

  • Roles are not entitled to 403s.
  • Valid paths continue to run.

Rollback risk:

  • Revert patch status guard.
  • Audit PO data that has changed during the issue window.

3) Add a new internal endpoint​

Purpose: provide data requirements for other modules.

Changed files:

  • Routes + new endpoint controller
  • Middleware access
  • docs/api-endpoints.md, docs/api-reference.md

Safe steps:

  1. Define the request/response contract clearly.
  2. Install minimum access middleware.
  3. Rate-limit if the endpoint is heavy.

Verification:

  • Only authorized roles can access.
  • Endpoint latency is still within team limits.

Rollback risk:

  • Disable new routes.
  • Revert release endpoint.

4) Integration credential rotation​

Goal: replace external service credentials without downtime.

Changed files:

  • Integration env/config files
  • docs/integration-points.md

Safe steps:

  1. Prepare a new credential (dual-valid if possible).
  2. Deploy with fallback to the old key (temporary).
  3. Test the read-only connection first.

Verification:

  • Integration request successful.
  • No spike in auth errors.

Rollback risk:

  • Return to the old credential which is still active.
  • Document rotation times.

5) Handle failed queue jobs​

Objective: recover failed jobs without duplicating side effects.

Changed files:

  • Related job handlers
  • Configure queue/retry
  • docs/observability-ops.md

Safe steps:

  1. Identify the root cause of failed_jobs/log.
  2. Make sure the job is idempotent before mass retry.
  3. Retry gradually.

Verification:

  • Failed job count goes down.
  • No duplicate data.

Rollback risk:

  • Stop retry.
  • Restore affected data if there is duplication.

6) Slow query patch​

Goal: reduce heavy endpoint response time.

Changed files:

  • Repository/query builder
  • Migration index (if necessary)
  • docs/database-design-full.md

Safe steps:

  1. Take a baseline query plan.
  2. Change the query/index one by one.
  3. Test performance on representative staging data.

Verification:

  • P95 latency improved.
  • Query results remain consistent.

Rollback risk:

  • Revert new query/index if write performance decreases.

7) Update input validation rules​

Purpose: close invalid data entering the system.

Changed files:

  • FormRequest/validator
  • Validation test
  • docs/api-cookbook.md

Safe steps:

  1. Mark new validations that have the potential to be breaking.
  2. If breaking, gradual release + communication.
  3. Add valid/invalid payload examples.

Verification:

  • Invalid input is rejected with a clear message.
  • Long valid input remains safe (if non-breaking).

Rollback risk:

  • Restore old rules temporarily.
  • Note the impact of invalid data that has already been entered.

8) Adjustment of role permissions​

Purpose: adjust access rights without opening loopholes.

Changed files:

  • Middleware/Policy/Gate
  • Seeder role-permission (if any)
  • docs/role-access-matrix.md

Safe steps:

  1. List of affected endpoints.
  2. Update policy + test access per role.
  3. Review by senior before merge.

Verification:

  • Target roles can be accessed as needed.
  • Other roles remain blocked.

Rollback risk:

  • Revert mapping permissions.
  • Audit access during the change period.

##9) Production bug hotfix (non-schema) Goal: fix critical bugs as quickly as possible but safely.

Changed files:

  • Bug source files (controller/service)
  • Regression test
  • docs/changelog.md

Safe steps:

  1. Reproduce bugs.
  2. Minimal patch (smallest safe fix).
  3. Add regression tests before deploying.

Verification:

  • Symptoms disappear.
  • The main line is not damaged.

Rollback risk:

  • Rollback hotfix release.
  • Enable temporary workarounds if available.

10) Business enum/state changes​

Objective: add/change state without breaking old flow.

Changed files:

  • Enum/model/validator status
  • State transition logic
  • docs/state-machine.md, docs/business-flows.md

Safe steps:

  1. Define a new complete state transition.
  2. Check the impact on reports, notifications and API.
  3. Backfill old data if necessary.

Verification:

  • Valid state transition according to flow.
  • Reports and notifications do not miscalculate.

Rollback risk:

  • Disable new status.
  • Restore data to old state (according to data playbook).