Add missing documentation#1510
Conversation
WalkthroughThis PR updates repository documentation: simplifies and consolidates test-running instructions in README.md (adds yarn test variants and workspace guidance), removes detailed Playwright UI-test setup and demo_survey notes, adds linting/formatting guidance, and introduces CONTRIBUTING.md with contribution, testing, submodule, and developer workflows. It deletes docs/development/README.md. It adds audit subsystem docs under packages/evolution-backend/src/services/audits (including auditChecks guidance and a checks index note) and updates docs/nomenclature.md renaming AuditCheck Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/nomenclature.md`:
- Line 40: The phrase "single person interview" in the AuditCheck description
should be hyphenated when used as a compound modifier; update the documentation
text for AuditCheck to use "single-person interview" (or restructure the
sentence to avoid the compound adjective) so style is consistent and clearer
when describing that classification in the AuditCheck examples.
In `@packages/evolution-backend/src/services/audits/README.md`:
- Line 34: Update the README.md fenced code blocks to satisfy markdown linting:
add language specifiers after each opening triple-backtick (e.g., ```bash,
```json, ```ts as appropriate), ensure there is a blank line before and after
each fenced block, and add a trailing newline at the end of the file so the file
ends with a newline character; locate the offending blocks by searching for the
triple-backtick fences (```) and apply these three fixes to each occurrence.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 4d0848cb-a2dc-43aa-8b3c-7d7e9391af4e
📒 Files selected for processing (4)
README.mddocs/development/README.mddocs/nomenclature.mdpackages/evolution-backend/src/services/audits/README.md
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (6)
- GitHub Check: check-format
- GitHub Check: build-and-test (24.x)
- GitHub Check: code-lint
- GitHub Check: pr-build-check
- GitHub Check: test-sequential (24.x)
- GitHub Check: generate-and-build-generator (24.x)
🧰 Additional context used
🧠 Learnings (6)
📚 Learning: 2025-10-26T10:48:46.701Z
Learnt from: kaligrafy
Repo: chairemobilite/evolution PR: 1306
File: packages/evolution-backend/src/services/audits/auditChecks/checks/InterviewAuditChecks.ts:137-152
Timestamp: 2025-10-26T10:48:46.701Z
Learning: In the Evolution project, audit checks in backend packages should remain decoupled from locale files. Audit checks return error codes with default English messages, and the frontend handles translation using locales. This separation ensures backend packages can be loaded without requiring the root locales folder.
Applied to files:
docs/nomenclature.mddocs/development/README.mdpackages/evolution-backend/src/services/audits/README.md
📚 Learning: 2025-09-08T16:08:58.098Z
Learnt from: kaligrafy
Repo: chairemobilite/evolution PR: 1203
File: packages/evolution-common/src/services/baseObjects/interview/Interview.ts:0-0
Timestamp: 2025-09-08T16:08:58.098Z
Learning: In the evolution codebase, type validation for interview attributes is handled during the audit process rather than enforcing strict types at the getter/setter level. The validate params should only validate types, not enforce business logic constraints.
Applied to files:
docs/nomenclature.md
📚 Learning: 2025-10-17T14:12:02.107Z
Learnt from: kaligrafy
Repo: chairemobilite/evolution PR: 1288
File: packages/evolution-common/src/config/__tests__/project.config.test.ts:11-19
Timestamp: 2025-10-17T14:12:02.107Z
Learning: In the evolution codebase, validation tests for `startDateTimeWithTimezoneOffset` and `endDateTimeWithTimezoneOffset` (ordering, format) should be added to specific project/survey configurations, not in the common library configuration tests (`packages/evolution-common/src/config/__tests__/project.config.test.ts`), since these dates/times are set in the survey config.
Applied to files:
README.md
📚 Learning: 2026-03-23T21:04:05.393Z
Learnt from: tahini
Repo: chairemobilite/evolution PR: 1447
File: packages/evolution-common/src/services/questionnaire/types/Data.ts:134-134
Timestamp: 2026-03-23T21:04:05.393Z
Learning: In `packages/evolution-common/src/services/questionnaire/types/Data.ts`, the `VisitedPlace` type (including `activity` and `activityCategory` fields) is the normalized questionnaire type, not the audit/persisted data type. Audits are migrated separately at their own pace. Since Evolution uses breaking versioning here, strict `Activity`/`ActivityCategory` union types are intentional and backward compatibility with legacy ids (e.g., `'work'`) is not required in this file.
Applied to files:
docs/development/README.mdpackages/evolution-backend/src/services/audits/README.md
📚 Learning: 2025-09-08T16:10:01.745Z
Learnt from: kaligrafy
Repo: chairemobilite/evolution PR: 1203
File: packages/evolution-common/src/services/baseObjects/Segment.ts:28-34
Timestamp: 2025-09-08T16:10:01.745Z
Learning: The InterviewStats.tsx file in packages/evolution-frontend/src/components/admin/validations/ is obsolete and should be updated separately, not as part of current PRs.
Applied to files:
docs/development/README.mdpackages/evolution-backend/src/services/audits/README.md
📚 Learning: 2025-09-30T11:00:03.295Z
Learnt from: kaligrafy
Repo: chairemobilite/evolution PR: 1225
File: packages/evolution-backend/src/services/audits/RestoreAttributes.ts:28-36
Timestamp: 2025-09-30T11:00:03.295Z
Learning: In packages/evolution-backend/src/services/audits/RestoreAttributes.ts, the restoreAttributes function intentionally performs unconditional assignment from originalResponse to correctedResponse, overwriting any existing corrected values even with undefined. This is by design for cases like restoring respondent language over admin review language, where the original value is needed for analysis regardless of whether it's defined.
Applied to files:
packages/evolution-backend/src/services/audits/README.md
🪛 LanguageTool
docs/nomenclature.md
[grammar] ~40-~40: Use a hyphen to join words.
Context: ...at least one transit trip", "is a single person interview"). When omitted, level ...
(QB_NEW_EN_HYPHEN)
packages/evolution-backend/src/services/audits/README.md
[style] ~138-~138: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...anup, not for the normal review flow. - It would spam the reviewer with low-value ...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🪛 markdownlint-cli2 (0.22.0)
packages/evolution-backend/src/services/audits/README.md
[warning] 34-34: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 153-153: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 153-153: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 156-156: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 157-157: Ordered list item prefix
Expected: 1; Actual: 5; Style: 1/2/3
(MD029, ol-prefix)
[warning] 158-158: Ordered list item prefix
Expected: 2; Actual: 6; Style: 1/2/3
(MD029, ol-prefix)
[warning] 316-316: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 387-387: Files should end with a single newline character
(MD047, single-trailing-newline)
🔇 Additional comments (12)
docs/nomenclature.md (1)
40-40: LGTM — terminology update aligns with implementation.The
type→levelrename andnote→infocategory change are consistent with the actual code (confirmed inPersonAuditChecks.ts). The default-to-error rule is clear.README.md (2)
159-169: Excellent addition — test commands documented clearly.The table accurately reflects the root
package.jsonscripts and the workspace targeting pattern is helpful for contributors.
305-307: LGTM — clean link to development guidelines.This points contributors to the right place for code style and audit documentation.
docs/development/README.md (2)
5-7: LGTM — code style guidance is concise and actionable.Points to the right tools, configs, and CI behavior. Clear.
9-19: LGTM — audit semantics documented accurately.The distinction from real-time validation is clear,
levelsemantics match the type definitions and migrations, and the link to the practical guide is helpful.packages/evolution-backend/src/services/audits/README.md (7)
1-19: LGTM — clear introduction and scope definition.The distinction between audit checks, real-time validation, and enhancers is helpful. The rule-of-thumb table is excellent.
34-81: LGTM — execution flow diagram is informative.The ASCII flow and key points accurately describe the audit pipeline based on the codebase structure.
144-164: LGTM — the 6-step checklist is comprehensive and actionable.The mandatory steps cover all necessary bases (function, translations, tests, local run, CHANGELOG, PR).
168-208: LGTM — helper documentation with working examples.The
fieldIsRequired,getSurveyArea, and geometry validation guidance is practical and points to live code.
211-296: LGTM — worked example is clear and complete.The
P_I_AgeOutOfRangeexample walks through all required steps with concrete code snippets. Very helpful for implementers.
339-349: LGTM — common pitfalls section is valuable.These gotchas (null vs undefined, missing translations, version bumps) will save debugging time.
6-6:⚠️ Potential issue | 🔴 CriticalFix broken relative paths in markdown links.
Several links use absolute-style paths (
../packages/...) that won't resolve correctly. Since this file is atpackages/evolution-backend/src/services/audits/README.md, relative paths should be adjusted:🔗 Proposed fixes for relative paths
-> `[packages/evolution-backend/src/services/audits/auditChecks/checks/README.md](../packages/evolution-backend/src/services/audits/auditChecks/checks/README.md)` +> `[packages/evolution-backend/src/services/audits/auditChecks/checks/README.md](./auditChecks/checks/README.md)`-`[auditChecks/AuditCheckContexts.ts](../packages/evolution-backend/src/services/audits/auditChecks/AuditCheckContexts.ts)`. +`[auditChecks/AuditCheckContexts.ts](./auditChecks/AuditCheckContexts.ts)`.-`[packages/evolution-backend/src/services/audits/auditChecks/checks/README.md](../packages/evolution-backend/src/services/audits/auditChecks/checks/README.md)` +`[packages/evolution-backend/src/services/audits/auditChecks/checks/README.md](./auditChecks/checks/README.md)`-`[evolution-common/src/services/audits/types.ts](../packages/evolution-common/src/services/audits/types.ts)`. +`[evolution-common/src/services/audits/types.ts](../../../evolution-common/src/services/audits/types.ts)`.-For date/time checks, look at how `I_I_StartedAtBeforeSurveyStartDate` and `I_I_StartedAtAfterSurveyEndDate` handle configuration in `InterviewAuditChecks.ts`, and the guidance in `[docs/SURVEY_END_DATE.md](./SURVEY_END_DATE.md)`. +For date/time checks, look at how `I_I_StartedAtBeforeSurveyStartDate` and `I_I_StartedAtAfterSurveyEndDate` handle configuration in `InterviewAuditChecks.ts`, and the guidance in `[docs/SURVEY_END_DATE.md](../../../../docs/SURVEY_END_DATE.md)`.Apply similar fixes to lines 367, 369, 371, 373, 382, and 383.
Also applies to: 106-106, 149-149, 183-183, 203-203, 367-367, 369-369, 371-371, 373-373, 382-382, 383-383
⛔ Skipped due to learnings
Learnt from: kaligrafy Repo: chairemobilite/evolution PR: 1306 File: packages/evolution-backend/src/services/audits/auditChecks/checks/InterviewAuditChecks.ts:137-152 Timestamp: 2025-10-26T10:48:46.701Z Learning: In the Evolution project, audit checks in backend packages should remain decoupled from locale files. Audit checks return error codes with default English messages, and the frontend handles translation using locales. This separation ensures backend packages can be loaded without requiring the root locales folder.Learnt from: tahini Repo: chairemobilite/evolution PR: 1447 File: packages/evolution-common/src/services/questionnaire/types/Data.ts:134-134 Timestamp: 2026-03-23T21:04:05.393Z Learning: In `packages/evolution-common/src/services/questionnaire/types/Data.ts`, the `VisitedPlace` type (including `activity` and `activityCategory` fields) is the normalized questionnaire type, not the audit/persisted data type. Audits are migrated separately at their own pace. Since Evolution uses breaking versioning here, strict `Activity`/`ActivityCategory` union types are intentional and backward compatibility with legacy ids (e.g., `'work'`) is not required in this file.Learnt from: kaligrafy Repo: chairemobilite/evolution PR: 1225 File: packages/evolution-backend/src/services/audits/auditChecks/checks/PersonAuditChecks.ts:18-33 Timestamp: 2025-09-30T15:23:22.212Z Learning: In the Evolution audit system, the `message` field in `AuditForObject` should be set to the `errorCode` value (or omitted) to enable proper i18n lookup. Hardcoded English messages should not be used in audit check return values.
|
|
||
| ## 2. How a check gets run (one diagram) | ||
|
|
||
| ``` |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Optional: address markdown linting hints.
Static analysis flags missing language specifiers on fenced code blocks (lines 34, 153, 316), missing blank lines around fences, and missing trailing newline. These don't affect functionality but improve consistency.
Also applies to: 153-156, 316-320, 387-387
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)
[warning] 34-34: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/evolution-backend/src/services/audits/README.md` at line 34, Update
the README.md fenced code blocks to satisfy markdown linting: add language
specifiers after each opening triple-backtick (e.g., ```bash, ```json, ```ts as
appropriate), ensure there is a blank line before and after each fenced block,
and add a trailing newline at the end of the file so the file ends with a
newline character; locate the offending blocks by searching for the
triple-backtick fences (```) and apply these three fixes to each occurrence.
kaligrafy
force-pushed
the
updateDocumentation
branch
2 times, most recently
from
e760108 to
0edf88f
Compare
tahini
left a comment
tahini
left a comment
There was a problem hiding this comment.
C'est bien en date d'aujourd'hui, mais il faut garder tout ça à jour. Et surtout, les audits dans Evolution, c'est pas mal nous qui allons les faire, avec les champs builtin et on va devoir s'adapter à différentes configuration du questionnaire (avec ou sans champ X et Y). Les administrateurs d'enquête, de leur côté, devront aussi ajouter leurs propres audits, pour aller avec leurs, qui ne seront pas dans evolution, et cette doc devra expliquer comment faire ça dans ces projets. (genre pour MJ et DA). Voilà ma préoccupation. Mais je ne bloquerai pas cette PR pour autant.
samuel-duhaime
left a comment
samuel-duhaime
left a comment
There was a problem hiding this comment.
Just a small recommendation.
greenscientist
left a comment
greenscientist
left a comment
There was a problem hiding this comment.
Is it time to move the "developpment" part of the README to a CONTRIB file instead?
kaligrafy
force-pushed
the
updateDocumentation
branch
from
0edf88f to
18ae036
Compare
done |
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@CONTRIBUTING.md`:
- Line 66: Update the example CLI invocation string that uses an unclear email
address: replace the sample email value in the command "yarn create-user
--username testUser --email user@test.ts --password testPassword --admin" with a
clearer, non-confusing placeholder such as "user@example.org" (or
"user@test.test") so the command example is unambiguous for contributors and
readers.
In `@packages/evolution-backend/src/services/audits/auditChecks/README.md`:
- Line 34: Update the fenced code blocks in the auditChecks README.md to satisfy
markdownlint: add explicit language tags (e.g., use ```text for the "Reviewer
opens interview…" ASCII diagram and ```bash for the yarn and rg command blocks)
and ensure a blank line separates surrounding text from each fenced block; apply
the same fixes to the other similarly malformed fences in the file (the other
command and example blocks referenced in the comment) so all code blocks include
a language tag and proper blank-line separation.
- Around line 148-149: Update the README guidance to stop requiring edits to
locale files: change the step that mandates adding translations in
locales/en/audits.json and locales/fr/audits.json for each audit errorCode to an
optional/UX-follow-up note, and clarify that backend audit checks (functions
returning errorCode and default English message) must remain decoupled from
front-end locales; keep the unit test requirement in
__tests__/<Object>/[ERROR_CODE].test.ts (with passing, failing, boundary/missing
cases) unchanged but remove any wording that ties test or check authoring to
updating locale files.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 81c78ce0-7bb6-457c-b13d-1a13a17dbbcb
📒 Files selected for processing (7)
CONTRIBUTING.mdREADME.mddocs/development/README.mddocs/nomenclature.mdpackages/evolution-backend/src/services/audits/README.mdpackages/evolution-backend/src/services/audits/auditChecks/README.mdpackages/evolution-backend/src/services/audits/auditChecks/checks/README.md
💤 Files with no reviewable changes (1)
- docs/development/README.md
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (5)
- GitHub Check: test-sequential (24.x)
- GitHub Check: code-lint
- GitHub Check: build-and-test (24.x)
- GitHub Check: pr-build-check
- GitHub Check: generate-and-build-generator (24.x)
🧰 Additional context used
🧠 Learnings (5)
📚 Learning: 2025-10-26T10:48:46.701Z
Learnt from: kaligrafy
Repo: chairemobilite/evolution PR: 1306
File: packages/evolution-backend/src/services/audits/auditChecks/checks/InterviewAuditChecks.ts:137-152
Timestamp: 2025-10-26T10:48:46.701Z
Learning: In the Evolution project, audit checks in backend packages should remain decoupled from locale files. Audit checks return error codes with default English messages, and the frontend handles translation using locales. This separation ensures backend packages can be loaded without requiring the root locales folder.
Applied to files:
packages/evolution-backend/src/services/audits/auditChecks/checks/README.mddocs/nomenclature.mdpackages/evolution-backend/src/services/audits/README.mdpackages/evolution-backend/src/services/audits/auditChecks/README.md
📚 Learning: 2025-10-17T14:12:02.107Z
Learnt from: kaligrafy
Repo: chairemobilite/evolution PR: 1288
File: packages/evolution-common/src/config/__tests__/project.config.test.ts:11-19
Timestamp: 2025-10-17T14:12:02.107Z
Learning: In the evolution codebase, validation tests for `startDateTimeWithTimezoneOffset` and `endDateTimeWithTimezoneOffset` (ordering, format) should be added to specific project/survey configurations, not in the common library configuration tests (`packages/evolution-common/src/config/__tests__/project.config.test.ts`), since these dates/times are set in the survey config.
Applied to files:
README.md
📚 Learning: 2025-09-08T16:08:58.098Z
Learnt from: kaligrafy
Repo: chairemobilite/evolution PR: 1203
File: packages/evolution-common/src/services/baseObjects/interview/Interview.ts:0-0
Timestamp: 2025-09-08T16:08:58.098Z
Learning: In the evolution codebase, type validation for interview attributes is handled during the audit process rather than enforcing strict types at the getter/setter level. The validate params should only validate types, not enforce business logic constraints.
Applied to files:
docs/nomenclature.mdpackages/evolution-backend/src/services/audits/README.md
📚 Learning: 2026-03-23T21:04:05.393Z
Learnt from: tahini
Repo: chairemobilite/evolution PR: 1447
File: packages/evolution-common/src/services/questionnaire/types/Data.ts:134-134
Timestamp: 2026-03-23T21:04:05.393Z
Learning: In `packages/evolution-common/src/services/questionnaire/types/Data.ts`, the `VisitedPlace` type (including `activity` and `activityCategory` fields) is the normalized questionnaire type, not the audit/persisted data type. Audits are migrated separately at their own pace. Since Evolution uses breaking versioning here, strict `Activity`/`ActivityCategory` union types are intentional and backward compatibility with legacy ids (e.g., `'work'`) is not required in this file.
Applied to files:
packages/evolution-backend/src/services/audits/README.mdCONTRIBUTING.mdpackages/evolution-backend/src/services/audits/auditChecks/README.md
📚 Learning: 2025-09-08T16:10:01.745Z
Learnt from: kaligrafy
Repo: chairemobilite/evolution PR: 1203
File: packages/evolution-common/src/services/baseObjects/Segment.ts:28-34
Timestamp: 2025-09-08T16:10:01.745Z
Learning: The InterviewStats.tsx file in packages/evolution-frontend/src/components/admin/validations/ is obsolete and should be updated separately, not as part of current PRs.
Applied to files:
CONTRIBUTING.mdpackages/evolution-backend/src/services/audits/auditChecks/README.md
🪛 LanguageTool
docs/nomenclature.md
[grammar] ~40-~40: Use a hyphen to join words.
Context: ...at least one transit trip", "is a single person interview"). When omitted, level ...
(QB_NEW_EN_HYPHEN)
CONTRIBUTING.md
[style] ~27-~27: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...through an issue describing the bug you want to fix or the feature you want to implemen...
(REP_WANT_TO_VB)
[style] ~27-~27: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ... bug you want to fix or the feature you want to implement. ## Coding guidelines To en...
(REP_WANT_TO_VB)
[style] ~107-~107: ‘prior to’ might be wordy. Consider a shorter alternative.
Context: ...urveys that used the evolution platform prior to May 2024. This will serve in the develo...
(EN_WORDINESS_PREMIUM_PRIOR_TO)
packages/evolution-backend/src/services/audits/auditChecks/README.md
[style] ~137-~137: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...anup, not for the normal review flow. - It would spam the reviewer with low-value ...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🪛 markdownlint-cli2 (0.22.0)
packages/evolution-backend/src/services/audits/auditChecks/README.md
[warning] 34-34: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 151-151: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 151-151: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 154-154: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 155-155: Ordered list item prefix
Expected: 1; Actual: 5; Style: 1/2/3
(MD029, ol-prefix)
[warning] 156-156: Ordered list item prefix
Expected: 2; Actual: 6; Style: 1/2/3
(MD029, ol-prefix)
[warning] 313-313: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (6)
docs/nomenclature.md (1)
40-40: Minor wording polish still pending (single-person interview).This was already pointed out earlier and still applies.
packages/evolution-backend/src/services/audits/auditChecks/README.md (1)
16-16: Please clarify “in-progress, during review”.This phrasing is still ambiguous (what is in progress exactly).
packages/evolution-backend/src/services/audits/auditChecks/checks/README.md (1)
5-6: Nice cross-linking improvement.The “start here” pointer is clear and helps navigation without duplicating content.
README.md (2)
159-170: Test command matrix looks good.Clear scope per command + practical workspace examples.
304-309: Documentation hub section is useful and complete.Good central linking to contributing, generator, and audits docs.
packages/evolution-backend/src/services/audits/README.md (1)
1-13: Great high-level audits overview.Short, clear semantics for
leveland a good pointer to the practical guide.
kaligrafy
force-pushed
the
updateDocumentation
branch
from
18ae036 to
e6db075
Compare
kaligrafy
force-pushed
the
updateDocumentation
branch
from
e6db075 to
d401dbb
Compare
kaligrafy
force-pushed
the
updateDocumentation
branch
2 times, most recently
from
76aae9d to
841a979
Compare
kaligrafy
force-pushed
the
updateDocumentation
branch
from
841a979 to
186b9dc
Compare
- Main README.md - move development doc to CONTRIBUTING.md and copy doc from transition - nomenclature.md (fix error) - audits/README.md - audits/auditChecks/README.md
kaligrafy
force-pushed
the
updateDocumentation
branch
from
186b9dc to
2284664
Compare
There was a problem hiding this comment.
♻️ Duplicate comments (3)
packages/evolution-backend/src/services/audits/auditChecks/README.md (3)
313-316: 🧹 Nitpick | 🔵 TrivialAdd language tag to grep command fence.
The shell command fence should specify
bash(orshell) as the language.Suggested fix
-``` +```bash rg -n "^\s+[IHMPJVTS]{1,2}_[MIL]_[A-Za-z]+:" \ packages/evolution-backend/src/services/audits/auditChecks/checks</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@packages/evolution-backend/src/services/audits/auditChecks/README.mdaround
lines 313 - 316, The code fence containing the ripgrep command (the block
starting withand the command rg -n "^\s+[IHMPJVTS]{1,2}_[MIL]_[A-Za-z]+:" \ ...) should include a language tag; update the opening fence fromtobash (orshell) so the command block is marked as bash/shell for proper syntax
highlighting and tooling.</details> --- `34-34`: _🧹 Nitpick_ | _🔵 Trivial_ **Add language tag to code fence.** The ASCII diagram fence should specify a language (e.g., `text`) for better rendering and accessibility. <details> <summary>Suggested fix</summary> ```diff -``` +```text Reviewer opens interview Admin triggers batch audit ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@packages/evolution-backend/src/services/audits/auditChecks/README.mdat line
34, The README's ASCII diagram code fence is missing a language tag; update the
fenced block in
packages/evolution-backend/src/services/audits/auditChecks/README.md by adding a
language identifier (e.g., change the openingtotext) so the diagram is
rendered/accessibility-friendly—locate the ASCII diagram block and modify its
opening fence to include "text".</details> --- `151-154`: _🧹 Nitpick_ | _🔵 Trivial_ **Add language tag and blank lines to code fence.** The commands fence should have a language tag (e.g., `bash`) and blank line separation for proper rendering. <details> <summary>Suggested fix</summary> ```diff -4. **Run locally**: - ``` +4. **Run locally**: + + ```bash yarn workspace evolution-backend test -- auditChecks yarn lint && yarn format - ``` + ``` + 5. **Add a CHANGELOG entry** ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@packages/evolution-backend/src/services/audits/auditChecks/README.mdaround
lines 151 - 154, Update the code fence in the auditChecks README so it includes
a language tag (e.g., bash) and is separated by blank lines before and after the
fenced block; locate the fenced block around the commands in README.md (the
three backticks showing the yarn commands) and change it to a fenced block likeclosing fence to ensure proper rendering.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@packages/evolution-backend/src/services/audits/auditChecks/README.md`:
- Around line 313-316: The code fence containing the ripgrep command (the block
starting with ``` and the command rg -n "^\s+[IHMPJVTS]{1,2}_[MIL]_[A-Za-z]+:" \
...) should include a language tag; update the opening fence from ``` to ```bash
(or ```shell) so the command block is marked as bash/shell for proper syntax
highlighting and tooling.
- Line 34: The README's ASCII diagram code fence is missing a language tag;
update the fenced block in
packages/evolution-backend/src/services/audits/auditChecks/README.md by adding a
language identifier (e.g., change the opening ``` to ```text) so the diagram is
rendered/accessibility-friendly—locate the ASCII diagram block and modify its
opening fence to include "text".
- Around line 151-154: Update the code fence in the auditChecks README so it
includes a language tag (e.g., bash) and is separated by blank lines before and
after the fenced block; locate the fenced block around the commands in README.md
(the three backticks showing the yarn commands) and change it to a fenced block
like ```bash with a blank line before the opening fence and a blank line after
the closing fence to ensure proper rendering.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 4f778cf2-8ac6-4aa2-a3b6-5d7f354373a7
📒 Files selected for processing (7)
CONTRIBUTING.mdREADME.mddocs/development/README.mddocs/nomenclature.mdpackages/evolution-backend/src/services/audits/README.mdpackages/evolution-backend/src/services/audits/auditChecks/README.mdpackages/evolution-backend/src/services/audits/auditChecks/checks/README.md
💤 Files with no reviewable changes (1)
- docs/development/README.md
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (6)
- GitHub Check: check-format
- GitHub Check: test-sequential (24.x)
- GitHub Check: build-and-test (24.x)
- GitHub Check: code-lint
- GitHub Check: pr-build-check
- GitHub Check: generate-and-build-generator (24.x)
🧰 Additional context used
🧠 Learnings (12)
📓 Common learnings
Learnt from: kaligrafy
Repo: chairemobilite/evolution PR: 1510
File: packages/evolution-backend/src/services/audits/auditChecks/README.md:148-149
Timestamp: 2026-04-21T14:52:26.321Z
Learning: In the Evolution project (packages/evolution-backend), adding a new audit check currently REQUIRES adding translations in locales/en/audits.json and locales/fr/audits.json. This is enforced by a CI test (AuditLocales.test.ts) and the UI resolves error codes via t('audits:${errorCode}'). Backend audit checks and frontend locales are tightly coupled today — decoupling is aspirational and would first require a code change (e.g. surfacing the `message` fallback in the UI and removing AuditLocales.test.ts) before any documentation change.
📚 Learning: 2026-04-21T14:52:26.321Z
Learnt from: kaligrafy
Repo: chairemobilite/evolution PR: 1510
File: packages/evolution-backend/src/services/audits/auditChecks/README.md:148-149
Timestamp: 2026-04-21T14:52:26.321Z
Learning: In the Evolution project (packages/evolution-backend), adding a new audit check currently REQUIRES adding translations in locales/en/audits.json and locales/fr/audits.json. This is enforced by a CI test (AuditLocales.test.ts) and the UI resolves error codes via t('audits:${errorCode}'). Backend audit checks and frontend locales are tightly coupled today — decoupling is aspirational and would first require a code change (e.g. surfacing the `message` fallback in the UI and removing AuditLocales.test.ts) before any documentation change.
Applied to files:
packages/evolution-backend/src/services/audits/auditChecks/checks/README.mddocs/nomenclature.mdpackages/evolution-backend/src/services/audits/README.mdREADME.mdCONTRIBUTING.mdpackages/evolution-backend/src/services/audits/auditChecks/README.md
📚 Learning: 2025-09-08T16:08:58.098Z
Learnt from: kaligrafy
Repo: chairemobilite/evolution PR: 1203
File: packages/evolution-common/src/services/baseObjects/interview/Interview.ts:0-0
Timestamp: 2025-09-08T16:08:58.098Z
Learning: In the evolution codebase, type validation for interview attributes is handled during the audit process rather than enforcing strict types at the getter/setter level. The validate params should only validate types, not enforce business logic constraints.
Applied to files:
docs/nomenclature.mdpackages/evolution-backend/src/services/audits/README.md
📚 Learning: 2026-03-23T21:04:05.393Z
Learnt from: tahini
Repo: chairemobilite/evolution PR: 1447
File: packages/evolution-common/src/services/questionnaire/types/Data.ts:134-134
Timestamp: 2026-03-23T21:04:05.393Z
Learning: In `packages/evolution-common/src/services/questionnaire/types/Data.ts`, the `VisitedPlace` type (including `activity` and `activityCategory` fields) is the normalized questionnaire type, not the audit/persisted data type. Audits are migrated separately at their own pace. Since Evolution uses breaking versioning here, strict `Activity`/`ActivityCategory` union types are intentional and backward compatibility with legacy ids (e.g., `'work'`) is not required in this file.
Applied to files:
packages/evolution-backend/src/services/audits/README.mdpackages/evolution-backend/src/services/audits/auditChecks/README.md
📚 Learning: 2025-10-17T14:12:02.107Z
Learnt from: kaligrafy
Repo: chairemobilite/evolution PR: 1288
File: packages/evolution-common/src/config/__tests__/project.config.test.ts:11-19
Timestamp: 2025-10-17T14:12:02.107Z
Learning: In the evolution codebase, validation tests for `startDateTimeWithTimezoneOffset` and `endDateTimeWithTimezoneOffset` (ordering, format) should be added to specific project/survey configurations, not in the common library configuration tests (`packages/evolution-common/src/config/__tests__/project.config.test.ts`), since these dates/times are set in the survey config.
Applied to files:
README.md
📚 Learning: 2025-09-08T16:12:48.175Z
Learnt from: kaligrafy
Repo: chairemobilite/evolution PR: 1203
File: packages/evolution-common/src/services/baseObjects/Segment.ts:28-34
Timestamp: 2025-09-08T16:12:48.175Z
Learning: The demo survey at example/demo_survey/src/survey/widgets/segments.tsx is obsolete and will be replaced by od_nationale_quebec soon, so it should not be updated as part of current PRs.
Applied to files:
CONTRIBUTING.md
📚 Learning: 2025-09-30T15:23:22.212Z
Learnt from: kaligrafy
Repo: chairemobilite/evolution PR: 1225
File: packages/evolution-backend/src/services/audits/auditChecks/checks/PersonAuditChecks.ts:18-33
Timestamp: 2025-09-30T15:23:22.212Z
Learning: In the Evolution audit system, the `message` field in `AuditForObject` should be set to the `errorCode` value (or omitted) to enable proper i18n lookup. Hardcoded English messages should not be used in audit check return values.
Applied to files:
packages/evolution-backend/src/services/audits/auditChecks/README.md
📚 Learning: 2025-10-08T14:42:41.348Z
Learnt from: greenscientist
Repo: chairemobilite/evolution PR: 1272
File: packages/evolution-frontend/src/actions/Survey.ts:797-798
Timestamp: 2025-10-08T14:42:41.348Z
Learning: In the evolution-frontend package, when reviewing production code that uses console.log for monitoring or observability purposes, remind the team to use structured logging or observability solutions (e.g., Sentry, DataDog) instead. The team wants to be reminded about this pattern.
Applied to files:
packages/evolution-backend/src/services/audits/auditChecks/README.md
📚 Learning: 2025-09-08T16:10:01.745Z
Learnt from: kaligrafy
Repo: chairemobilite/evolution PR: 1203
File: packages/evolution-common/src/services/baseObjects/Segment.ts:28-34
Timestamp: 2025-09-08T16:10:01.745Z
Learning: The InterviewStats.tsx file in packages/evolution-frontend/src/components/admin/validations/ is obsolete and should be updated separately, not as part of current PRs.
Applied to files:
packages/evolution-backend/src/services/audits/auditChecks/README.md
📚 Learning: 2025-09-30T11:00:03.295Z
Learnt from: kaligrafy
Repo: chairemobilite/evolution PR: 1225
File: packages/evolution-backend/src/services/audits/RestoreAttributes.ts:28-36
Timestamp: 2025-09-30T11:00:03.295Z
Learning: In packages/evolution-backend/src/services/audits/RestoreAttributes.ts, the restoreAttributes function intentionally performs unconditional assignment from originalResponse to correctedResponse, overwriting any existing corrected values even with undefined. This is by design for cases like restoring respondent language over admin review language, where the original value is needed for analysis regardless of whether it's defined.
Applied to files:
packages/evolution-backend/src/services/audits/auditChecks/README.md
📚 Learning: 2026-04-16T17:49:13.237Z
Learnt from: tahini
Repo: chairemobilite/evolution PR: 1504
File: packages/evolution-common/src/services/questionnaire/sections/visitedPlaces/sectionVisitedPlaces.ts:71-103
Timestamp: 2026-04-16T17:49:13.237Z
Learning: In `packages/evolution-common/src/services/questionnaire/sections/visitedPlaces/sectionVisitedPlaces.ts`, the hardcoded `departurePlaceOther` → `activity`/`activityCategory` mapping in `addInitialVisitedPlaces` is intentional and temporary. The departure place question itself is not yet part of Evolution; once it is, the mapping will be improved/made configurable. A FIXME comment is already present in the code to document this.
Applied to files:
packages/evolution-backend/src/services/audits/auditChecks/README.md
📚 Learning: 2026-04-10T18:03:22.157Z
Learnt from: tahini
Repo: chairemobilite/evolution PR: 1491
File: packages/evolution-common/src/services/questionnaire/types/SectionConfig.ts:554-565
Timestamp: 2026-04-10T18:03:22.157Z
Learning: In `packages/evolution-common/src/services/questionnaire/types/SectionConfig.ts`, runtime validation for `tripDiaryMinTimeOfDay` and `tripDiaryMaxTimeOfDay` (e.g., >= 0, sensible upper bound, min < max) is intentionally deferred. Validation will be handled at a single centralized entry point when the full trip diary/questionnaire configuration system is implemented. For now, values are accepted as-is.
Applied to files:
packages/evolution-backend/src/services/audits/auditChecks/README.md
🪛 LanguageTool
docs/nomenclature.md
[grammar] ~40-~40: Use a hyphen to join words.
Context: ...at least one transit trip", "is a single person interview"). When omitted, level ...
(QB_NEW_EN_HYPHEN)
CONTRIBUTING.md
[style] ~27-~27: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...through an issue describing the bug you want to fix or the feature you want to implemen...
(REP_WANT_TO_VB)
[style] ~27-~27: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ... bug you want to fix or the feature you want to implement. ## Coding guidelines To en...
(REP_WANT_TO_VB)
packages/evolution-backend/src/services/audits/auditChecks/README.md
[style] ~137-~137: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...anup, not for the normal review flow. - It would spam the reviewer with low-value ...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🪛 markdownlint-cli2 (0.22.1)
packages/evolution-backend/src/services/audits/auditChecks/README.md
[warning] 34-34: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 151-151: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 151-151: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 154-154: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 155-155: Ordered list item prefix
Expected: 1; Actual: 5; Style: 1/2/3
(MD029, ol-prefix)
[warning] 156-156: Ordered list item prefix
Expected: 2; Actual: 6; Style: 1/2/3
(MD029, ol-prefix)
[warning] 313-313: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (12)
packages/evolution-backend/src/services/audits/auditChecks/checks/README.md (1)
5-6: Excellent navigation aid.The blockquote clearly distinguishes this tactical reference from the broader practical guide and helps readers navigate the documentation hierarchy effectively.
docs/nomenclature.md (1)
40-40: Nomenclature update aligns with code.The field renames (
type→level,note→info) and default behavior correctly match theAudittype definition and support the new audits documentation.README.md (3)
159-168: Test instructions are clearer and more concise.The table format and workspace targeting guidance improve usability over the previous verbose approach.
170-176: Good addition of linting/formatting guidance.Clear and concise for contributors.
229-234: Documentation links are well-organized.The new section properly connects contributors to the relevant guides added in this PR.
packages/evolution-backend/src/services/audits/README.md (1)
1-14: Excellent audits subsystem documentation.This clearly explains post-submission validation, correctly distinguishes audits from real-time validation, and accurately documents the level semantics. The link to the practical guide completes the documentation set.
packages/evolution-backend/src/services/audits/auditChecks/README.md (5)
1-30: Clear introduction and scope.The audience statement and the decision table (lines 23-27) effectively help readers determine whether they need an audit check or a different mechanism.
34-73: Pipeline diagram is helpful.The flow diagram effectively shows how checks integrate into the audit orchestration pipeline. The context information at lines 75-81 correctly describes async behavior, error handling, and version management.
84-141: Excellent decision framework.The four-question structure (object, problem type, severity, standard vs extended) with clear tables and practical guidance will help contributors make consistent choices.
143-162: Comprehensive implementation checklist and helper guidance.The 6-step checklist correctly requires translations (enforced by CI per learnings), and the helpers section provides practical examples for common patterns. Based on learnings: translations in locales/en/audits.json and locales/fr/audits.json are required by AuditLocales.test.ts.
Also applies to: 165-205
208-290: Worked example and pitfalls are valuable.The P_I_AgeOutOfRange example walks through all required steps clearly. The pitfalls section (lines 336-346) addresses common mistakes that will save contributors time.
Also applies to: 320-372
CONTRIBUTING.md (1)
1-140: Comprehensive and well-organized contributing guide.This covers all essential aspects: contribution types, coding standards, testing (properly aligned with the simplified commands in README.md), UI testing setup with Playwright, and links to the new audit documentation. Excellent resource for contributors.
| - An example file with the Quebec province area is available at `example/demo_survey/surveyArea.geojson.example`. | ||
|
|
||
| ## Run UI tests for the application | ||
| ## Running tests |
There was a problem hiding this comment.
Quelles sont les règles pour aller dans Contributing vs README? Pourquoi les tests UI sont maintenant dans contributing, mais tests et linting sont ici? Ça ne devrait pas aller à la même place?
There was a problem hiding this comment.
Aucune idée! SVP suggérer
There was a problem hiding this comment.
Aucune idée! SVP suggérer
Je réfléchis ici...
imho, Evolution est un framework qui applique des méthodes d'enquêtes en transport. On en parle en conférences, on en fait la promotion sur la place publique, mais on n'a pas de page d'introduction dédiée. On en aura peut-être une via éventuellement #1525, qui permettra d'améliorer le tout, mais bref, des gens de différents horizons risquent de tomber sur la page github.
Le README principal est la façade d'Evolution: on doit y mettre l'information pertinente à lire pour des gens intéressés à faire des enquêtes de transport (donc utiliser Evolution pour produire des enquêtes). Le README ne devrait pas être trop long et surtout contenir de l'information sur pour les cas d'utilisation principaux, avec des liens vers de la documentation plus détaillé pour chaque auditoire.
Selon cette logique, rouler les tests de la plateforme ne devrait pas être dans le README principal, mais dans une doc pour contributeur à la plateforme (qui est le fichier contributing).
samuel-duhaime
left a comment
samuel-duhaime
left a comment
There was a problem hiding this comment.
J'ai la même interrogation que @tahini .
Quel contenu doit aller dans le contributing ou dans le readme?
Comment faire pour s'assurer qu'on ne répète pas les mêmes sections (avec une plus grande chance de ne pas pouvoir maintenir tout)
SVP suggérer quelque chose. Je ne sais pas! |
4 participants
Summary by CodeRabbit