DX-D04: Update contributing setup documentation - #41
Closed
w196n8y-hub wants to merge 47 commits into
Closed
Conversation
Trim overseer from local-paths, run npm start, add a docker proxy that points at doubtfire-api, and document the run steps and failures.
This pull request template includes sections for Jira ticket, summary, target branch, testing, security and privacy, evidence, and a checklist to ensure thorough review.
chore(deploy): add mail catcher and web push keys to the local dev stack
…uest-template Add pull request template for consistent submissions
worked on fixing podman compatablity
Three people lost an evening to the same local setup failure this week. Two hit "Tablespace is missing for a table" during rake db:populate and could not get past it, one ran the populate command on the host instead of in the container. The database data directory is a bind mount on the host, so it survives docker compose down -v and gets reused indefinitely. The compose files pulled an unpinned mariadb tag, so two people who set up a month apart got two different majors pointed at the same folder layout. Pin both development compose files to 12.3, which is the version the working stack was verified against. Once that folder is unreadable, db:populate cannot fix it: the drop is the step that fails. The guide said to rerun step 2, which is exactly what does not work. Problem 5 now carries the full stop, delete the folder, up, populate sequence with the PowerShell form alongside the POSIX one. Also add problem 14 for the tablespace error itself, problem 15 for running bundle on the host by mistake, and a check at the top of problem 6 so a dead api container is not misread as the proxy bug.
Three people hit setup problems this week and all three sent screenshots of terminals. Two were cropped above the line that mattered, and one was a photo of a Word document containing a screenshot of a terminal, which is two lossy steps away from the text. Add an Asking for help section between the health checks and the problem list, which is where someone already is when they get stuck. It asks for docker ps -a rather than docker ps, because an exited container is invisible to the latter and is usually the whole problem, and it asks for the two container logs as attached files rather than as pictures. Also ask which branch each repo is on and whether both -f flags were used. A third of the entries in the problem list turn on those two things and we currently have to ask every time.
The command added in the previous commit does not survive PowerShell. A plain > redirect writes UTF-16, so the file reads as binary to most tools, and PowerShell wraps native stderr in error objects, which separates the error message from the stack trace that explains it. The first log captured with it came back needing iconv to read, with 'rake aborted!' split away from the ActiveRecord exception below it. Wrapping in cmd /c avoids both. Keep the plain form for macOS and Linux.
Formatted commands in RUNNING-LOCALLY.md with code blocks for better readability.
…cument-reset fix(dev): pin the dev database image and document the hard reset
Three people on Windows could not get the stack up. All three failed on rake db:populate with errno 194, Tablespace is missing for a table, on the same table. It is not corruption and not stale data. It reproduces on a database created seconds earlier: two of them deleted the data directory, brought the stack up clean and got the identical error on the identical table. InnoDB cannot reliably rename a table when its files are on a host directory shared into the container on Windows. Loading the schema renames tables while it adds foreign keys, so it fails on the first one every time. MariaDB/mariadb-docker#331 reproduces it in three statements, and it does not happen without the bind mount. Use a named db_data volume instead, so the database lives inside Docker's own filesystem. docs/ONTRACK_PODMAN_SETUP.md already reached this conclusion for Podman and docker-compose.podman.yml already does it; this applies the same fix to the base compose. Rewrite problem 14 around the real cause, change problem 5's reset from deleting a folder to down -v, and correct problem 8, which said down -v does not delete your database. That was true under the bind mount and is false now. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
fix(dev): move the dev database off the host bind mount
…ault The API does enforce a minimum cohort size. RUNNING-LOCALLY.md said it did not, which is wrong in the direction that matters on a privacy control and would send someone hunting a config bug that is really a 503. Raise DF_PPI_MINIMUM_COHORT_SIZE from 5 to 20 to match PeerProgressApi::MINIMUM_SAFE_COHORT_SIZE, explain why the floor and the quantisation bucket are a matched pair, and record the API commit the wording was checked against. Also record a BEFORE count in the local verification recipe, so a second run cannot read as a pass, and note that seeded units are too small to clear the floor.
…ess-local-settings chore(deploy): configure local peer progress defaults
* Add configurable marker notification thresholds * fix(ci): gate the Teams notifier and harden its payload Adds a job guard so the webhook is unreachable from anonymous fork pull requests on these public repositories, and so the file is inert if it ever travels to thoth-tech or doubtfire-lms. Adds reopened and ready_for_review, which is the transition a reviewer alert exists to catch, and varies the headline per action so it stays accurate. Strips Markdown link and code syntax from the title, author and head label before they reach the channel. Joins on a double newline, which is what Teams renders as a break. Reports the real HTTP status instead of asserting a delivery the workflow never checked. --------- Co-authored-by: Clupai8o0 <clupaio4@gmail.com>
Refactor Teams notification to use Adaptive Card
Simplified condition for triggering notification.
GitHub gates on the test merge commit whenever that commit carries a status, and only falls back to the head when it carries none. The test merge commit carries none of this repository's other checks, so reporting there moves the merge gate onto a commit CI never sees, and that commit is recomputed every time the base branch moves. Report on head.sha instead. A recomputed test merge commit is no longer something the evaluator reports on, so drop it from the mid-evaluation consistency check as well. 14 unit tests pass.
…view-policy ci: enforce OnTrack PR review policy
The membership step read secrets.TEAM_MEMBERSHIP_TOKEN, which does not exist. The organisation secret is TEAM_MEMBERSHIP_ACCESS, so the step hit its own missing-secret guard and failed on every pull request in all three repositories. The author login also went into the curl URL unencoded and without --globoff, so a login containing brackets made curl exit before sending anything. dependabot[bot] is exactly that shape, which turned every dependency bump into a red check. A pull request from a branch in this repository now short-circuits to eligible without an API call, which is what kept Dependabot and every in-org branch notifying before this workflow grew a step. Membership state "pending" counts alongside "active", so a teammate who has not accepted their organisation invitation is no longer skipped. A skip emits a warning naming the author, because a silent skip was the failure mode this step was added to remove. The Adaptive Card payload is restored to what is on 11.0.x. Replacing it with a flat text body was not part of this change.
Nothing in the api sets a queue, so a worker taking default would run AcceptSubmissionJob, which every task submission enqueues and which raises because development has no texlive service. Every dev submission would drop to fix with an automated comment on it. The worker takes mailers only, which doubtfire-api#43 puts the notification email job on. The Podman override had no block for the new service, so it resolved to a March 2025 8.0.x image while the api resolved to the local 11.0 build, and its binds lost their selinux relabel. It now mirrors the api block. The worker also gets a restart policy, a health-gated dependency on Redis so a lost startup race is not permanent and silent, and a TZ, because three of the seven cron entries name a wall-clock time. RUNNING-LOCALLY.md described queued delivery as current behaviour. It now says what the worker is for and names api#43 as what changes it.
…lidation-20260826 ci: add required pull request validation
…fications chore(ci): notify Teams for verified team members
…rker chore(deploy): run Sidekiq worker locally
…ction-values-20260824 fix(ppi): configure approved production values
The compare call 404s once a source or target branch is deleted, and with set -euo pipefail that fails the whole weekly job instead of skipping the entry. Check both refs exist first and exit 0 when either is missing.
…y-integration-prs-20260826 ci: add weekly integration PR automation
Author
|
Closing this PR because it included unrelated commit history. A clean replacement PR has been opened as #42. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Updates
CONTRIBUTING.mdto improve and simplify the development setup documentation for DX-D04.Changes
Validation
git diff --checkpasses with no errors.CONTRIBUTING.mdwas modified.