From 70e6a1382bccad6477efdce2f9240761cc29d8c3 Mon Sep 17 00:00:00 2001 From: Valerio Giuffrida Date: Mon, 31 Aug 2026 17:35:31 +0200 Subject: [PATCH 1/5] Update CONTRIBUTING.md including SD email inbox --- docs/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 6c4ddb3..7520e87 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -77,6 +77,6 @@ We use a **monorepo** structure and follow **trunk-based development**. All new ## πŸ’¬ Communication -If you have questions about the workflow or need to contact an admin regarding an existing issue, please use the project's [Discussion/Contact Method]. +If you have questions about the workflow or need to contact an admin regarding an existing issue, please use this project's issues or reach out to **global.surveydesigner@wfp.org**. **Thank you for helping us make Survey Designer better!** From 51e8d00307f9106d7317b900f6f7196c79ef071b Mon Sep 17 00:00:00 2001 From: Valerio Giuffrida Date: Mon, 31 Aug 2026 18:02:49 +0200 Subject: [PATCH 2/5] Revise GOVERNANCE.md - missing items linkage - Linking missing items with placeholder documents and populate new issue with other todo #160 --- docs/GOVERNANCE.md | 39 ++++++++++++++++++--------------------- 1 file changed, 18 insertions(+), 21 deletions(-) diff --git a/docs/GOVERNANCE.md b/docs/GOVERNANCE.md index f957979..d7c70be 100644 --- a/docs/GOVERNANCE.md +++ b/docs/GOVERNANCE.md @@ -19,8 +19,7 @@ ## Triagers -Triagers assess newly-opened issues in the [survey-designer][] and [survey-designer-documentation/help][] -repositories. The GitHub team for survey-designer triagers is @[placeholder]. +Triagers assess newly-opened issues in the [survey-designer][] repository and [project](https://github.com/orgs/wfp/projects/11). The GitHub team for survey-designer triagers is @[placeholder]. Triagers are given the "Triage" GitHub role and have: * Ability to label issues and pull requests @@ -33,11 +32,11 @@ See: ## Collaborators -SurveyDesigner core collaborators maintain the [survey-designer][] GitHub repository. +SurveyDesigner core collaborators maintain the [survey-designer](https://github.com/wfp/surveydesigner) GitHub repository. The GitHub team for SurveyDesigner core collaborators is @[placeholder/]survey-designer/collaborators. Collaborators have: -* Commit access to the [survey-designer][] repository +* Commit access to the [survey-designer](https://github.com/wfp/surveydesigner) repository * Access to the SurveyDesigner continuous integration (CI) jobs Both collaborators and non-collaborators may propose changes to the SurveyDesigner @@ -91,7 +90,7 @@ The current list of TSC members is in [the project README](./README.md#current-project-team-members). The [TSC Charter][] governs the operations of the TSC. All changes to the -Charter need approval by the Foundation Cross-Project Council (CPC). +Charter need approval by the director of the department managing the solution. ### TSC meetings @@ -157,7 +156,7 @@ To clarify, TSC voting members can object to the vote taking place during the meeting, but not to the vote itself. For discussions outside of meetings, the TSC uses -[the TSC discussions](https://github.com/survey-designer-documentation/TSC/discussions) for public +[the TSC discussions]() for public issues, and the private TSC email list for private matters. The process for public issues in the issue tracker is: @@ -228,7 +227,7 @@ but it is important. To nominate a new Collaborator: 1. **Optional but strongly recommended**: open a - [discussion in the survey-designer-documentation][] repository. Provide a summary of + [discussion in the survey-designer](https://github.com/wfp/surveydesigner/) repository. Provide a summary of the nominee's contributions (see below for an example). 2. **Optional but strongly recommended**: After sufficient wait time (e.g. 72 hours), if the nomination proposal has received some support and no explicit @@ -238,7 +237,7 @@ To nominate a new Collaborator: nomination issue if I don't hear any objections in the next 72 hours". 3. **Optional but strongly recommended**: Privately contact the nominee to make sure they're comfortable with the nomination. -4. Link relevant issues from the [survey-designer][] repository. Provide a summary of +4. Link relevant issues from the [survey-designer](https://github.com/wfp/surveydesigner/) repository. Provide a summary of the nominee's contributions (see below for an example). Mention collaborators in the issue to notify other collaborators about the nomination. @@ -251,19 +250,19 @@ certain the nominee is fine with the public scrutiny. Example of list of contributions: -* Commits in the [survey-designer][] repository. - * Use the link `https://github.com/nodejs/node/commits?author=GITHUB_ID` -* Pull requests and issues opened in the [survey-designer][] repository. - * Use the link `https://github.com/nodejs/node/issues?q=author:GITHUB_ID` -* Comments on pull requests and issues in the [survey-designer][] repository - * Use the link `https://github.com/nodejs/node/issues?q=commenter:GITHUB_ID` -* Reviews on pull requests in the [survey-designer][] repository - * Use the link `https://github.com/nodejs/node/pulls?q=reviewed-by:GITHUB_ID` +* Commits in the [survey-designer](https://github.com/wfp/surveydesigner/) repository. + * Use the link `https://github.com/wfp/surveydesigner/commits?author=GITHUB_ID` +* Pull requests and issues opened in the [survey-designer](https://github.com/wfp/surveydesigner/) repository. + * Use the link `https://github.com/wfp/surveydesigner/issues?q=author:GITHUB_ID` +* Comments on pull requests and issues in the [survey-designer](https://github.com/wfp/surveydesigner/) repository + * Use the link `https://github.com/wfp/surveydesigner/issues?q=commenter:GITHUB_ID` +* Reviews on pull requests in the [survey-designer](https://github.com/wfp/surveydesigner/) repository + * Use the link `https://github.com/wfp/surveydesigner/pulls?q=reviewed-by:GITHUB_ID` * Help provided to end-users and novice contributors * Pull requests and issues opened throughout the SurveyDesigner projects - * Use the link `https://github.com/search?q=author:GITHUB_ID+org:nodejs` + * Use the link `https://github.com/search?q=author:GITHUB_ID+org:wfp` * Comments on pull requests and issues throughout the SurveyDesigner projects - * Use the link `https://github.com/search?q=commenter:GITHUB_ID+org:nodejs` + * Use the link `https://github.com/search?q=commenter:GITHUB_ID+org:wfp` * Participation in other projects, teams, and working groups of the SurveyDesigner organization * Other participation in the wider SurveyDesigner community @@ -341,6 +340,4 @@ The TSC follows a [Consensus Seeking][] decision-making model per the [Consensus Seeking]: https://en.wikipedia.org/wiki/Consensus-seeking_decision-making [TSC Charter]: https://github.com/nodejs/TSC/blob/HEAD/TSC-Charter.md -[discussion in the nodejs/collaborators]: https://github.com/nodejs/collaborators/discussions/categories/collaborator-nominations -[nodejs/help]: https://github.com/nodejs/help -[nodejs/node]: https://github.com/nodejs/node +[survey-designer]: https://github.com/wfp/surveydesigner From 056d06066e3e55b89599998e39c62a9a90b2f3cb Mon Sep 17 00:00:00 2001 From: Valerio Giuffrida Date: Mon, 31 Aug 2026 18:04:42 +0200 Subject: [PATCH 3/5] Create TSC_CHARTER.md Placeholder charter for technical steering committee created. --- docs/doc/TSC/TSC_CHARTER.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 docs/doc/TSC/TSC_CHARTER.md diff --git a/docs/doc/TSC/TSC_CHARTER.md b/docs/doc/TSC/TSC_CHARTER.md new file mode 100644 index 0000000..ffd0b8f --- /dev/null +++ b/docs/doc/TSC/TSC_CHARTER.md @@ -0,0 +1,3 @@ +# Technical Steering Committee (TSC) Charter + +## Section 1. Guiding Principle From b03a160a69753aad8588f14b361c08ee66c6039b Mon Sep 17 00:00:00 2001 From: Valerio Giuffrida Date: Mon, 31 Aug 2026 18:08:14 +0200 Subject: [PATCH 4/5] added link to TSC charter - ./ONBOARDING.md - ./doc/TSC/TSC_CHARTER.md --- docs/GOVERNANCE.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/GOVERNANCE.md b/docs/GOVERNANCE.md index d7c70be..bfd58c3 100644 --- a/docs/GOVERNANCE.md +++ b/docs/GOVERNANCE.md @@ -330,7 +330,7 @@ the nominee once they are onboarded. ### Onboarding After the nomination passes, a TSC member onboards the new collaborator. See -[the onboarding guide](./ONBOARDING.md) for details of the onboarding +[the onboarding guide][] for details of the onboarding process. ## Consensus seeking process @@ -339,5 +339,6 @@ The TSC follows a [Consensus Seeking][] decision-making model per the [TSC Charter][]. [Consensus Seeking]: https://en.wikipedia.org/wiki/Consensus-seeking_decision-making -[TSC Charter]: https://github.com/nodejs/TSC/blob/HEAD/TSC-Charter.md +[TSC Charter]: ./doc/TSC/TSC_CHARTER.md [survey-designer]: https://github.com/wfp/surveydesigner +[the onboarding guide]: ./ONBOARDING.md From 7ebd8ed2c8b67ce1906138e828a855298aa786e2 Mon Sep 17 00:00:00 2001 From: "Leandro E. Bravo" Date: Thu, 3 Sep 2026 16:47:06 +0200 Subject: [PATCH 5/5] docs: add full architecture section and reorganize governance docs - Add verified full-architecture section to TECHNICAL_VALUES.md covering the service topology, Keycloak/OIDC authentication (incl. IDENTITY_PROVIDER switch and CIAM backend), and the i18next + translationcli.py localization pipeline, with rationale for each choice - Move WORKING_GROUPS.md to top-level docs/ alongside GOVERNANCE.md and fix its relative links; update docs/README.md index accordingly - Add docs/README.md index and remove obsolete docs/doc/TSC/ files --- docs/CONTRIBUTING.md | 18 +- docs/GOVERNANCE.md | 181 ++++----- docs/MODERATION_POLICY.md | 58 +-- docs/ONBOARDING.md | 441 ++++++++++------------ docs/README.md | 62 +++ docs/WORKING_GROUPS.md | 42 +++ docs/doc/ROADMAP_GUIDANCE.md | 44 ++- docs/doc/TSC/TSC_CHARTER.md | 3 - docs/doc/TSC/WORKING_GROUPS.md | 1 - docs/doc/TSC/voting/README.md | 1 - docs/doc/contributing/TECHNICAL_VALUES.md | 108 +++++- 11 files changed, 556 insertions(+), 403 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/WORKING_GROUPS.md delete mode 100644 docs/doc/TSC/TSC_CHARTER.md delete mode 100644 docs/doc/TSC/WORKING_GROUPS.md delete mode 100644 docs/doc/TSC/voting/README.md diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 7520e87..2091324 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -15,7 +15,7 @@ By contributing to this project, you agree that your contributions will be licen If you discover a security-related bug: 1. **Do not** create a GitHub issue. -2. **Email:** Send a detailed report to **leandro.bravo@wfp.org**. +2. **Email:** Send a detailed report to **global.surveydesigner@wfp.org**. 3. **Template:** Please use the standard security reporting template in your email. --- @@ -42,10 +42,20 @@ We use a **monorepo** structure and follow **trunk-based development**. All new 1. **Develop:** Work on your changes within your designated branch. 2. **Pull Request:** Create a PR targeting the main trunk. **Crucial:** Ensure the PR description **contains a direct link to the relevant GitHub issue** and explicitly mentions your branch name. 3. **Testing & Security:** We require manual testing before submitting a PR. - - **Frontend:** Run `pnpm test:ci` to execute the frontend tests. - - **Backend:** Run `docker compose run api test-ci` to execute the backend tests. + - **Frontend:** Run `pnpm test:ci` to execute the frontend tests with coverage. + - **Backend:** Run `docker compose run api test-ci` to execute the backend tests with coverage. + - **Branch coverage:** Every change must keep **branch coverage above 85%**. + Coverage is collected with branch coverage enabled for both applications + (`@vitest/coverage-v8` for the frontend and `--cov` with `branch = True` + for the backend). See + [Technical Values & Development Principles](doc/contributing/TECHNICAL_VALUES.md#test-automation--ci-compliance) + for the exact commands and configuration. + - **End-to-end:** Where your change affects user-facing flows, run the + Playwright suite with `pnpm e2e:ci` (see + [`react-ui/e2e/README.md`](../react-ui/e2e/README.md)). - **Security:** Run a Trivy scan to ensure there are no security vulnerabilities. - - **Note:** You must fix any failing tests or security issues before your PR can be merged. + - **Note:** You must fix any failing tests, coverage regressions, or security + issues before your PR can be merged. 4. **Approval:** Maintainers will review the code. If changes are requested, add comments and push updates to your branch. ### 4. Merging diff --git a/docs/GOVERNANCE.md b/docs/GOVERNANCE.md index bfd58c3..6fdfb2e 100644 --- a/docs/GOVERNANCE.md +++ b/docs/GOVERNANCE.md @@ -1,4 +1,3 @@ - # SurveyDesigner Project Governance @@ -6,8 +5,8 @@ * [Triagers](#triagers) * [Collaborators](#collaborators) * [Collaborator activities](#collaborator-activities) -* [Technical steering committee](#technical-steering-committee) - * [TSC meetings](#tsc-meetings) +* [The SurveyDesigner maintainers team](#the-surveydesigner-maintainers-team) +* [Decision-making](#decision-making) * [Collaborator nominations](#collaborator-nominations) * [Who can nominate Collaborators?](#who-can-nominate-collaborators) * [Ideal Nominees](#ideal-nominees) @@ -19,7 +18,7 @@ ## Triagers -Triagers assess newly-opened issues in the [survey-designer][] repository and [project](https://github.com/orgs/wfp/projects/11). The GitHub team for survey-designer triagers is @[placeholder]. +Triagers assess newly-opened issues in the [survey-designer][] repository and [project](https://github.com/orgs/wfp/projects/11). The GitHub team for survey-designer triagers is @wfp/surveydesigner. Triagers are given the "Triage" GitHub role and have: * Ability to label issues and pull requests @@ -27,13 +26,12 @@ Triagers are given the "Triage" GitHub role and have: See: -* [List of triagers](./README.md#triagers) -* [A guide for triagers](./doc/contributing/issues.md#triaging-a-bug-report) +* [A guide for contributors](./CONTRIBUTING.md) ## Collaborators SurveyDesigner core collaborators maintain the [survey-designer](https://github.com/wfp/surveydesigner) GitHub repository. -The GitHub team for SurveyDesigner core collaborators is @[placeholder/]survey-designer/collaborators. +The GitHub team for SurveyDesigner core collaborators is @wfp/surveydesigner. Collaborators have: * Commit access to the [survey-designer](https://github.com/wfp/surveydesigner) repository @@ -49,15 +47,15 @@ than 7 days.) Approving a pull request indicates that the collaborator accepts responsibility for the change. Approval must be from collaborators who are not authors of the change. -If a collaborator opposes a proposed change, then the change cannot land. The -exception is if the TSC votes to approve the change despite the opposition. -Usually, involving the TSC is unnecessary. Often, discussions or further changes -result in collaborators removing their opposition. +If a collaborator opposes a proposed change, then the change cannot land. +Usually the opposition is resolved through discussion or further changes. If the +maintainers cannot reach consensus, the project admin makes the final call (see +[Decision-making](#decision-making)). See: -* [List of collaborators](./README.md#current-project-team-members) -* [A guide for collaborators](./doc/contributing/collaborator-guide.md) +* [A guide for contributors](./CONTRIBUTING.md) +* [The onboarding guide for new collaborators](./ONBOARDING.md) ### Collaborator activities @@ -67,17 +65,20 @@ See: * Participation in working groups * Merging pull requests -The TSC can remove inactive collaborators or provide them with _emeritus_ -status. Emeriti may request that the TSC restore them to active status. +The maintainers team can remove inactive collaborators or provide them with +_emeritus_ status. Emeriti may request that the maintainers team restore them to +active status. A collaborator is automatically made emeritus (and removed from active collaborator status) if it has been more than 12 months since the collaborator has authored or approved a commit that has landed. -## Technical Steering Committee +## The SurveyDesigner maintainers team -A subset of the collaborators forms the Technical Steering Committee (TSC). -The TSC has final authority over this project, including: +The project is governed by **the SurveyDesigner maintainers team** β€” the +collaborators in the [@wfp/surveydesigner GitHub team](https://github.com/orgs/wfp/teams/surveydesigner). +There is no separate steering committee; the maintainers team holds final +authority over the project, including: * Technical direction * Project governance and process (including this policy) @@ -86,85 +87,32 @@ The TSC has final authority over this project, including: * Conduct guidelines * Maintaining the list of collaborators -The current list of TSC members is in -[the project README](./README.md#current-project-team-members). - -The [TSC Charter][] governs the operations of the TSC. All changes to the -Charter need approval by the director of the department managing the solution. - -### TSC meetings - -The TSC meets in a video conference call. Each year, the TSC elects a chair to -run the meetings. The TSC streams its meetings for public viewing on YouTube. - -TSC meetings may consist of a public portion and a private portion. The private -portion is used to discuss sensitive topics, such as personnel issues, -security vulnerabilities, or other confidential matters. Private discussions -should be avoided as much as possible, and the TSC should strive to keep -discussions in the public portion of the meeting, but there are times when -private discussions are necessary. - -The TSC agenda includes issues that are at an impasse. The intention of the -agenda is not to review or approve all patches. Collaborators review and approve -patches on GitHub. The preference is to minimize the need for TSC meetings to -make decisions that can otherwise be made by collaborators on GitHub. - -Any community member can create a GitHub issue asking that the TSC review -something. If consensus-seeking fails for an issue, a collaborator may apply the -`tsc-agenda` label. That will add it to the TSC meeting agenda. - -Before each TSC meeting, the meeting chair will share the agenda with members of -the TSC. TSC members can also add items to the agenda at the beginning of each -meeting. The meeting chair and the TSC cannot veto or remove items. - -The TSC may invite people to take part in a non-voting capacity in either the -public or private portions of the meeting. - -During the public portion of the meeting, the TSC chair ensures that someone -takes minutes that include a summary of the discussion and any -decisions made. After the meeting, the TSC chair ensures that someone opens a -public pull request with the minutes from the public portion of the meeting. - -The public portion of the TSC meeting is expected to be recorded and made -available for live streaming during the meeting or download by anyone after. -This expectation is to be announced to all participants at the start of the -each meeting before the recording is started. Continued participation in the -public portion of the meeting after this announcement is interpreted as consent to the -recording. - -For the private portion of the meeting, the TSC chair ensures that someone -produces a summary of the discussions, gets it reviewed by the attendees, -and shares it to all the TSC members once approved by the attendees via a -private discussion channel such as the TSC private mailing list. The summary -may be made public if there is consensus within the TSC and the non-TSC -attendees to make it public. - -Recording the private portion of a meeting or maintaining or publishing a -detailed transcript is only permitted when all participants present during the -private portion of the meeting explicitly agree to the recording and/or -transcript, in order to comply to privacy regulations. - -All discussions made during meetings are considered provisional, receiving no -objections from folks at the TSC meeting to take an action is not equivalent to -the TSC endorsing that action. - -If a quorum of TSC voting members is present, it is possible to call for an -explicit vote, and take the vote immediately if there are no objections. The -decision is considered confirmed once the rest of the TSC voting members have -been informed and no objection for taking that vote has been raised in 48 hours. -To clarify, TSC voting members can object to the vote taking place during the -meeting, but not to the vote itself. - -For discussions outside of meetings, the TSC uses -[the TSC discussions]() for public -issues, and the private TSC email list for private matters. The process for -public issues in the issue tracker is: - -* A TSC member opens a thread explaining the proposal/issue and mentions the TSC group. -* The proposal passes if, after 72 hours, there are two or more TSC voting - member approvals and no TSC voting member opposition. -* If there is an extended impasse, a TSC member may ask for the issue to be - added to the TSC agenda, or make a motion for a vote. +One maintainer acts as the project **admin**. The admin is responsible for +organization-level administration (repository and team settings, access +management) and breaks ties when the maintainers cannot reach consensus. + +Changes to this governance policy are proposed as pull requests and follow the +[Consensus seeking process](#consensus-seeking-process). Changes that affect the +project's relationship with its host department also require approval by the +director of the department managing the solution. + +## Decision-making + +The maintainers team makes decisions by **consensus**: + +* Most decisions are made directly on GitHub through pull request review and + issue discussion. Routine changes do not need any special process beyond the + normal two-approval rule described under [Collaborators](#collaborators). +* When a decision cannot be made through normal review β€” for example a + disagreement about direction or an issue at an impasse β€” any maintainer may + open an issue describing the question and mention the maintainers team. The + proposal is adopted if, after a reasonable period (typically 72 hours), there + is support from the maintainers and no sustained, unresolved opposition. +* If consensus still cannot be reached, the **admin makes the final decision** + and records the rationale in the relevant issue or pull request. + +Any community member can open a GitHub issue asking the maintainers team to +review something. ## Collaborator nominations @@ -174,7 +122,7 @@ Existing Collaborators can nominate someone to become a Collaborator. ### Ideal Nominees -Nominees should have significant and valuable contributions across the Node.js +Nominees should have significant and valuable contributions across the SurveyDesigner organization. Contributions can be: @@ -217,10 +165,10 @@ It is not uncommon for malicious actors to attempt to gain commit access to open-source projects in order to inject malicious code or for other nefarious purposes. The SurveyDesigner project has a number of mechanisms in place to prevent this, but it is important to be vigilant. If you have concerns about the -authenticity of a contributor, please raise them with the TSC. Anyone nominating -a new collaborator should take reasonable steps to verify that the contributions -of the nominee are authentic and made in good faith. This is not always easy, -but it is important. +authenticity of a contributor, please raise them with the maintainers team. +Anyone nominating a new collaborator should take reasonable steps to verify that +the contributions of the nominee are authentic and made in good faith. This is +not always easy, but it is important. ### Nominating a new Collaborator @@ -268,13 +216,14 @@ Example of list of contributions: * Other participation in the wider SurveyDesigner community The nomination passes if no collaborators oppose it (as described in the -following section) after one week. In the case of an objection, the TSC is -responsible for working with the individuals involved and finding a resolution. -The TSC may, following typical TSC consensus seeking processes, choose to -advance a nomination that has otherwise failed to reach a natural consensus or -clear path forward even if there are outstanding objections. The TSC may also -choose to prevent a nomination from advancing if the TSC determines that any -objections have not been adequately addressed. +following section) after one week. In the case of an objection, the maintainers +team is responsible for working with the individuals involved and finding a +resolution. Following the [Consensus seeking process](#consensus-seeking-process), +the maintainers team may choose to advance a nomination that has otherwise +failed to reach a natural consensus or clear path forward even if there are +outstanding objections. The maintainers team may also choose to prevent a +nomination from advancing if it determines that any objections have not been +adequately addressed. #### How to review a collaborator nomination @@ -322,23 +271,25 @@ the public issue is opened. Opposition _should_ be paired with clear suggestions for positive, concrete, and unambiguous next steps that the nominee can take to overcome the objection and allow it to move forward. While such suggestions are technically optional, they are _strongly encouraged_ to prevent the nomination -from stalling indefinitely or objections from being overridden by the TSC. +from stalling indefinitely or objections from being overridden by the maintainers +team. Remember that all private discussions about a nomination will be visible to the nominee once they are onboarded. ### Onboarding -After the nomination passes, a TSC member onboards the new collaborator. See -[the onboarding guide][] for details of the onboarding +After the nomination passes, a member of the maintainers team onboards the new +collaborator. See [the onboarding guide][] for details of the onboarding process. ## Consensus seeking process -The TSC follows a [Consensus Seeking][] decision-making model per the -[TSC Charter][]. +The SurveyDesigner maintainers team follows a [Consensus Seeking][] +decision-making model: the team seeks consensus first, and where consensus +cannot be reached the project admin breaks the tie, as described under +[Decision-making](#decision-making). [Consensus Seeking]: https://en.wikipedia.org/wiki/Consensus-seeking_decision-making -[TSC Charter]: ./doc/TSC/TSC_CHARTER.md [survey-designer]: https://github.com/wfp/surveydesigner [the onboarding guide]: ./ONBOARDING.md diff --git a/docs/MODERATION_POLICY.md b/docs/MODERATION_POLICY.md index d7a9bb5..25b7350 100644 --- a/docs/MODERATION_POLICY.md +++ b/docs/MODERATION_POLICY.md @@ -30,7 +30,7 @@ supported by the Admin team of the Slack organization. * *Collaborator* refers to any individual with configured triage role or higher in any SurveyDesigner GitHub Project repository. See [GitHub's Repository roles documentation][] for more information. -* *TSC* refers to the [Technical Steering Committee][]. +* *Maintainers team* refers to the [SurveyDesigner maintainers team][]. * *Post* refers to the content and titles of any issue, pull request, comment, discussion, or wiki page. * *Moderate* means to modify, lock, or delete one or more Posts to correct or @@ -77,7 +77,7 @@ to all members of the Moderation Team. When a request is sent by email to the [global.surveydesigner@wfp.org][] (or directly to a Moderation Team member) the moderation team must log the issue internally and -report it periodically to the TSC. +report it periodically to the maintainers team. Requests should contain as much information and context as possible, including the URL and a screenshot of the Post in question. Screenshots may be modified @@ -176,7 +176,7 @@ a Post from Moderation. it is possible to hide comments of non-Collaborators. In that case there is an exception to the reporting requirement described above. * Accounts that are reasonably believed to be bots (other than bots authorized - by the TSC) are subject to immediate Blocking. + by the maintainers team) are subject to immediate Blocking. * Issues, pull requests, discussions, and comments that are spam (job posting, service advertising, etc.) are subject to immediate moderation. * Issues, pull requests, discussions, and comments that are believed to be @@ -188,7 +188,7 @@ a Post from Moderation. get blocked if they do it again. * Collaborators may use the Hide feature in the GitHub interface for off-topic posts by non-Collaborators. -* Moderation Team members and TSC voting members can delete any issues or +* Moderation Team members and maintainers team members can delete any issues or comments posted by accounts that have been deleted by GitHub. These accounts show up in the GitHub interface as user `ghost`. There is no need to screenshot or document these deletions. @@ -263,15 +263,16 @@ The SurveyDesigner Moderation Team is tasked with enforcement of this policy. Moderation team members have the same expectations as other leadership groups as outlined in the [Member expectation][] document. At least once per month, the Moderation Team must provide a report of all Moderation -actions taken by the Moderation Team to the TSC. +actions taken by the Moderation Team to the maintainers team. *Nomination* Moderation team members are Collaborators who self-nominate or are nominated by -the TSC. Team members must be approved by the TSC with annual -recertification. If there are no objections after seven days, the nomination is automatically -accepted. If there are objections to a specific nomination, then a TSC vote -in favor of the nomination is required. +the maintainers team. Team members must be approved by the maintainers team with +annual recertification. If there are no objections after seven days, the +nomination is automatically accepted. If there are objections to a specific +nomination, then approval by the maintainers team (by consensus, with the admin +breaking any tie) is required. *Onboarding* @@ -284,11 +285,11 @@ New Moderation Team members are onboarded with: *Recertification* An annual recertification vote is required for all Moderation Team members. -For an individual to be recertified, a TSC vote in favor of recertification is required. +For an individual to be recertified, approval by the maintainers team is required. *Departure* -A TSC vote is required to remove a moderator who has not resigned. +A decision by the maintainers team is required to remove a moderator who has not resigned. *Resignation* @@ -314,7 +315,7 @@ remove resigning team member from respective permissions and private access. **Valerio Giuffrida** <> (he/him) * [hatemgkotb](https://github.com/hatemgkotb) - - **Hatem Kotb** < (he/him) + **Hatem Kotb** <> (he/him) ## Escalation of issues @@ -328,27 +329,28 @@ Any code of conduct report, and any decision made by the moderation team, can be appealed to the Code of Conduct Team following the [appeal process][]. -## Reports regarding TSC and Moderation team members +## Reports regarding maintainers team and Moderation team members -Moderation disputes involving TSC or Moderation Team members, -including questions of whether a TSC or Moderation Team member has -failed the Code of Conduct, are to be handled by the other TSC members. -This process will be mediated by a volunteer from the moderation team. +Moderation disputes involving maintainers team or Moderation Team members, +including questions of whether a maintainers team or Moderation Team member has +failed the Code of Conduct, are to be handled by the other maintainers team +members. This process will be mediated by a volunteer from the moderation team. -TSC or Moderation Team members directly involved in a Moderation +Maintainers team or Moderation Team members directly involved in a Moderation issue (as either the Requester or author of the Post in question) are required to recuse themselves from any decisions required to resolve the issue. ## Modifications to This Policy -Modifications to this policy are subject to approval by the TSC. +Modifications to this policy are subject to approval by the maintainers team. When modifications are proposed, if there are no objections after -72 hours, the modifications are accepted. If there any objections to -any proposed change, a TSC vote in favor of the change is required. +72 hours, the modifications are accepted. If there are any objections to +any proposed change, approval by the maintainers team (by consensus, with the +admin breaking any tie) is required. -[Code of Conduct]: https://github.com/nodejs/admin/blob/master/CODE_OF_CONDUCT.md -[Technical Steering Committee]: https://github.com/WFP-VAM/survey-designer-documentation/blob/main/GOVERNANCE.md#technical-steering-committee +[Code of Conduct]: CODE_OF_CONDUCT.md +[SurveyDesigner maintainers team]: GOVERNANCE.md#the-surveydesigner-maintainers-team [GitHub's Repository roles documentation]: https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization#repository-roles-for-organizations [GitHub's Temporary Interaction Limits]: https://github.com/blog/2370-introducing-temporary-interaction-limits [Applicability]: #applicability @@ -361,15 +363,15 @@ any proposed change, a TSC vote in favor of the change is required. [Non-Collaborator Posts]: #non-collaborator-posts [Temporary Interaction Limits]: #temporary-interaction-limits [Temporary and Indefinite Blocks]: #temporary-and-indefinite-blocks -[Privacy of the `survey-designer-moderation` Repository]: #privacy-of-the-nodejsmoderation-repository +[Privacy of the `survey-designer-moderation` Repository]: #privacy-of-the-survey-designer-moderation-repository [Moderation Team]: #moderation-team [Moderation Team members]: #current-members [Escalation of Issues]: #escalation-of-issues [Modifications to This Policy]: #modifications-to-this-policy [global.surveydesigner@wfp.org]: mailto:global.surveydesigner@wfp.org [block other individuals from their personal GitHub accounts]: https://help.github.com/en/articles/blocking-a-user-from-your-personal-account -[GitHub Projects]: https://github.com/nodejs/admin/blob/master/GITHUB_ORG_MANAGEMENT_POLICY.md +[GitHub Projects]: https://github.com/orgs/wfp/teams/surveydesigner [WFP Slack Community]: https://wfp.slack.com/ -[escalation process]: https://github.com/openjs-foundation/cross-project-council/blob/main/conduct/COC_POLICY.md#escalation -[appeal process]: https://github.com/openjs-foundation/cross-project-council/blob/main/conduct/COC_POLICY.md#appeals -[Member expectation]: https://github.com/nodejs/admin/blob/master/MemberExpectations.md +[escalation process]: GOVERNANCE.md#decision-making +[appeal process]: GOVERNANCE.md#decision-making +[Member expectation]: CODE_OF_CONDUCT.md diff --git a/docs/ONBOARDING.md b/docs/ONBOARDING.md index 397f0ea..255a0bb 100644 --- a/docs/ONBOARDING.md +++ b/docs/ONBOARDING.md @@ -4,76 +4,163 @@ This document is an outline of the things we tell new collaborators at their onboarding session. > [!NOTE] -> **Open Access & Public Contributions:** The Survey Designer repository is a fully public repository. Anyone who requests access and is approved by the Technical Steering Committee (TSC) or project maintainers can contribute. We actively encourage public participation and aim to maintain a welcoming, low-barrier entry point for all qualified collaborators. - -## One week before the onboarding session - -* If the new Collaborator is not yet a member of the WFP GitHub organization, +> **Open access & public contributions:** The Survey Designer repository is a +> fully public repository. Anyone who requests access and is approved by the +> SurveyDesigner maintainers team can contribute. We +> actively encourage public participation and aim to maintain a welcoming, +> low-barrier entry point for all qualified collaborators. + +## Contents + +* [Before the onboarding session](#before-the-onboarding-session) +* [Onboarding session](#onboarding-session) +* [Repository layout](#repository-layout) +* [Local setup](#local-setup) + * [Backend (Django, containerized)](#backend-django-containerized) + * [Frontend (React, local)](#frontend-react-local) + * [End-to-end tests (Playwright)](#end-to-end-tests-playwright) +* [Project goals and values](#project-goals-and-values) +* [Managing the issue tracker](#managing-the-issue-tracker) +* [Reviewing pull requests](#reviewing-pull-requests) +* [Landing pull requests](#landing-pull-requests) +* [Final notes](#final-notes) + +## Before the onboarding session + +* If the new collaborator is not yet a member of the WFP GitHub organization, confirm that they are using [two-factor authentication][]. It will not be possible to add them to the organization if they are not using two-factor - authentication. If they cannot receive SMS messages from GitHub, try - [using a TOTP mobile app][]. + authentication. +* Prior to the onboarding session, add the new collaborator to the + [@wfp/surveydesigner team][the collaborators team]. +* Confirm the new collaborator has Docker, Node.js 20.x, `pnpm`, Python 3.11, + and Poetry available locally (see [Local setup](#local-setup)). + +## Onboarding session +This session will cover: -## Fifteen minutes before the onboarding session +* [local setup](#local-setup) +* [project goals and values](#project-goals-and-values) +* [managing the issue tracker](#managing-the-issue-tracker) +* [reviewing pull requests](#reviewing-pull-requests) +* [landing pull requests](#landing-pull-requests) -* Prior to the onboarding session, add the new Collaborator to - [the collaborators team][]. -* Ask them if they want to join any [subsystem teams][] - and add them accordingly. See [Who to CC in the issue tracker][who-to-cc]. +## Repository layout -## Onboarding session +Survey Designer is a **decoupled monorepo**. The two applications live in the +same repository but run as independent runtimes: + +| Directory | Application | Stack | +| :--- | :--- | :--- | +| `react-ui/` | Frontend Single Page Application | React 18, TypeScript, Vite, Vitest, Playwright | +| `dj-be/` | Backend API and Django admin | Django 5.2, Django REST Framework, PostgreSQL, Redis, MinIO, Keycloak | +| `docs/` | Project and governance documentation | Markdown | +| `.github/` | Issue templates and GitHub workflows | β€” | -* This session will cover: - * [local setup](#local-setup) - * [project goals and values](#project-goals-and-values) - * [managing the issue tracker](#managing-the-issue-tracker) - * [reviewing pull requests](#reviewing-pull-requests) - * [landing pull requests](#landing-pull-requests) +For a deeper explanation of the architecture and engineering principles, read +the [Technical Values and Development Principles][Technical Values] document. ## Local setup * git: - * Make sure you have whitespace=fix: `git config --global --add - apply.whitespace fix` - * Always create a branch in your own GitHub fork for pull requests - * Branches in the `survey-designer` repository are only for release lines - * Add the canonical `survey-designer` repository as `upstream` remote: - * `git remote add upstream git@github.com:wfp/survey-designer.git` + * Always create a branch in your own GitHub fork for pull requests. + Branches in the `surveydesigner` repository are reserved for release lines. + * Add the canonical `surveydesigner` repository as the `upstream` remote: + * `git remote add upstream git@github.com:wfp/surveydesigner.git` * To update from `upstream`: * `git checkout main` * `git fetch upstream HEAD` * `git reset --hard FETCH_HEAD` - * Make a new branch for each pull request you submit. - * Membership: Consider making your membership in the WFP GitHub - organization public. This makes it easier to identify collaborators. - Instructions on how to do that are available at + * Make a new branch for each pull request you submit, following the branch + naming standard in [CONTRIBUTING.md][] (for example + `issue/42-fix-login`). + * Membership: consider making your membership in the WFP GitHub organization + public. This makes it easier to identify collaborators. See [Publicizing or hiding organization membership][]. -* Notifications: - * Use or - set up email - * Watching the main repository will flood your inbox (several hundred - notifications on typical weekdays), so be prepared - * Watching the discussions in the - [documentation repo](https://github.com/wfp-vam/survey-designer-documentation) is recommended. - -The project has a venue for real-time discussion: - -* [`#survey-designer`](https://wfp.slack.com/archives/C01J35WMDRT) on - the [WFP Slack Community][] +* Install `pre-commit` hooks in each application you work on: + * `pre-commit install` (a `.pre-commit-config.yaml` exists in both + `react-ui/` and `dj-be/`). + +### Backend (Django, containerized) + +The backend requires coordinated services (PostgreSQL, Redis, MinIO, Keycloak, +Maildev). To avoid "works on my machine" issues, it runs entirely in Docker. + +```sh +cd dj-be +cp .env.sample .env # then adjust values as needed +docker compose up --build # starts api, worker, postgres, redis, minio, keycloak, maildev +``` + +* The API is served on `http://localhost:8080` (Keycloak on `:8081`, Maildev on + `:1080`, MinIO console on `:9001`). +* Django management tasks are wrapped in the `dj-be/Makefile`. Common targets: + * `make migrate` β€” run migrations and seed data (`init_users`, + `generate_data`, etc.). + * `make run_dev` β€” Django `runserver` on `0:8080`. + * `make lint` β€” `flake8`, `black --check`, `isort --check-only`. + * `make test` β€” lint, `makemigrations --check`, then `pytest`. + * `make collectstatic` β€” collect static assets. + +### Frontend (React, local) + +The frontend runs locally on the host for fast Hot Module Replacement. + +```sh +cd react-ui +pnpm install +pnpm dev # Vite dev server on http://localhost:3000 +``` + +Point the frontend at the backend container through the +`VITE_APP_API_ENDPOINT` environment variable. Useful scripts (from +`react-ui/package.json`): + +* `pnpm dev` β€” Vite dev server. +* `pnpm build` β€” production build to `dist/`. +* `pnpm lint` / `pnpm lint:fix` β€” ESLint over `src/app`. +* `pnpm pretty` β€” Prettier formatting. +* `pnpm tsc` β€” TypeScript type check (`tsc --noEmit`). +* `pnpm test` β€” Vitest in watch mode. +* `pnpm test:ci` β€” `vitest run --coverage` (used for CI and pre-merge checks). + +### End-to-end tests (Playwright) + +Playwright drives the React frontend against the **real** local Django stack β€” +the API is not mocked. Full details are in [`react-ui/e2e/README.md`][e2e readme]. + +```sh +# 1. Start the backend stack with the E2E environment file +cd dj-be +docker compose --env-file .env.e2e up -d --build +curl --fail http://localhost:8080/health/ + +# 2. Install the browser and run the headless smoke suite +cd ../react-ui +pnpm install +pnpm exec playwright install chromium +pnpm e2e:ci # playwright test --project=chromium +``` + +Interactive debugging is available with `pnpm e2e:ui`. Authenticated tests use +`POST /auth/e2e-login/`, which is only registered when `ENABLE_E2E_AUTH=true`, +`ENV` is `ci` or `test`, and `E2E_AUTH_TOKEN` is set (see the e2e README). ## Project goals and values -* Collaborators are the collective owners of the project - * The project has the goals of its contributors +* Collaborators are the collective owners of the project. + * The project has the goals of its contributors. -* There are some higher-level goals and values - * Empathy towards users matters (this is in part why we onboard people) +* There are some higher-level goals and values: + * Empathy towards users matters (this is in part why we onboard people). * Generally: try to be nice to people! * The best outcome is for people who come to our issue tracker to feel like they can come back again. - * Understand our decoupled architectural setup, local pnpm/Node frontend environment, dockerized backend services, and trunk-based development workflow by reviewing the [Technical Values and Development Principles][Technical Values]. + * Understand our decoupled architecture, the local `pnpm`/Vite frontend + environment, the dockerized Django backend, and our trunk-based development + workflow by reviewing the [Technical Values and Development Principles][Technical Values]. * You are expected to follow _and_ hold others accountable to the [Code of Conduct][]. @@ -85,45 +172,20 @@ The project has a venue for real-time discussion: * Be nice about closing issues! Let people know why, and that issues and pull requests can be reopened if necessary. -* See [Labels][]. - * Issue templates enable auto-labelling of the queries received. - * There is [a bot][] that - applies subsystem labels (for example, `doc`, `test`, `assert`, or `buffer`) - so that we know what parts of the code base the pull request modifies. It is - not perfect, of course. Feel free to apply relevant labels and remove - irrelevant labels from pull requests and issues. - * `semver-{minor,major}`: - * If a change has the remote _chance_ of breaking something, use the - `semver-major` label - * When adding a `semver-*` label, add a comment explaining why you're adding - it. Do it right away so you don't forget! - * Please add the [`author-ready`][] label for pull requests, if applicable. - -* See [Who to CC in the issue tracker][who-to-cc]. - * This will come more naturally over time - * For many of the teams listed there, you can ask to be added if you are - interested - * Some are WGs with some process around adding people, others are only there - for notifications +* Issues are created from the templates in [`.github/ISSUE_TEMPLATE`][issue templates] + (Bug, Feature, Epic, User Story, Task). + * The [Issue Hierarchy Validator][] GitHub workflow enforces parent/child + relationships between Epics, Features, User Stories, and Tasks. If an issue + is missing a valid parent, the workflow comments and applies the + `invalid-hierarchy` label. + * Feel free to apply relevant labels and remove irrelevant labels from pull + requests and issues. + * When a change has the remote _chance_ of breaking something, treat it as a + `MAJOR` change per our [Release Management & Tagging Strategy][Release Management]. * When a discussion gets heated, you can request that other collaborators keep - an eye on it by opening an issue at the private - [survey-designer/moderation](https://github.com/WFP/survey-designer-moderation) repository. Note - that while that repository is not public, it can be accessed by anyone in the - SurveyDesigner project, so refrain from using it to report individuals (reporting - spam/bots there is fine of course). - * This is a repository to which all members of the `SurveyDesigner` GitHub - project (not just collaborators on `survey-designer` core) have access. Its - contents should not be shared externally. - * SurveyDesigner has a moderation team which you should contact when unsure - about taking action in the SurveyDesigner project. - * You can moderate non-collaborator posts yourself. Please - report the moderation action taken in accordance to the moderation - policy. - * You can always refer to the - [full moderation policy](MODERATION_POLICY.md). - * You can contact someone in the - [full list of moderation team members](MODERATION_POLICY.md#current-members-of-moderation-team). + an eye on it. Refer to the [Moderation Policy][] for the full process and the + [list of Moderation Team members][moderation members]. ## Reviewing pull requests @@ -133,187 +195,70 @@ The project has a venue for real-time discussion: pull request from a new contributor is an opportunity to grow the community. * Review a bit at a time. Do not overwhelm new contributors. - * It is tempting to micro-optimize. Don't succumb to that temptation. We - change V8 often. Techniques that provide improved performance today may be - unnecessary in the future. -* Be aware: Your opinion carries a lot of weight! +* Be aware: your opinion carries a lot of weight! * Nits (requests for small changes that are not essential) are fine, but try to avoid stalling the pull request. * Identify them as nits when you comment: `Nit: change foo() to bar().` * If they are stalling the pull request, fix them yourself on merge. -* Insofar as possible, issues should be identified by tools rather than human - reviewers. If you are leaving comments about issues that could be identified - by tools but are not, consider implementing the necessary tooling. - -* Minimum wait for comments time - * There is a minimum waiting time which we try to respect for non-trivial - changes so that people who may have important input in such a distributed - project are able to respond. - * For non-trivial changes, leave the pull request open for at least 48 hours. - * If a pull request is abandoned, check if they'd mind if you took it over - (especially if it just has nits left). - -* Approving a change - * Collaborators indicate that they have reviewed and approve of the changes in - a pull request using GitHub's approval interface - * Some people like to comment `LGTM` (β€œLooks Good To Me”) +* Insofar as possible, issues should be identified by tools (ESLint, Prettier, + `tsc`, flake8, black, isort) rather than human reviewers. + +* Verify the required checks before approving: + * Frontend: `pnpm lint`, `pnpm tsc`, and `pnpm test:ci` pass. + * Backend: `make test` (or `docker compose run api test-ci`) passes. + * Branch coverage must be **greater than 85%** (see + [CONTRIBUTING.md][] and [Technical Values][]). + * Where relevant, the Playwright suite (`pnpm e2e:ci`) passes. + * A Trivy scan reports no new vulnerabilities. + +* Minimum wait for comments time: + * For non-trivial changes, leave the pull request open for at least 48 hours + so people in a distributed project can respond. + * If a pull request is abandoned, check if the author would mind if you took + it over (especially if it just has nits left). + +* Approving a change: + * Collaborators approve using GitHub's review interface. * You have the authority to approve any other collaborator's work. * You cannot approve your own pull requests. - * When explicitly using `Changes requested`, show empathy – comments will - usually be addressed even if you don't use it. - * If you do, it is nice if you are available later to check whether your - comments have been addressed - * If you see that the requested changes have been made, you can clear - another collaborator's `Changes requested` review. - * Use `Changes requested` to indicate that you are considering some of your - comments to block the pull request from landing. - -* What belongs in SurveyDesginer: - * Opinions vary – it's good to have a broad collaborator base for that reason! - * If SurveyDesigner itself needs it (due to historical reasons), then it belongs in - SurveyDesigner. - * That is to say, `url` is there because of `http`, `freelist` is there - because of `http`, etc. - * Things that cannot be done outside of core, or only with significant pain - such as `async_hooks`. - -* Continuous Integration (CI) Testing: - * - * It is not automatically run. You need to start it manually. - * Log in on CI is integrated with GitHub. Try to log in now! - * You will be using `node-test-pull-request` most of the time. Go there now! - * Consider bookmarking it: - * To get to the form to start a job, click on `Build with Parameters`. (If you - don't see it, that probably means you are not logged in!) Click it now! - * To start CI testing from this screen, you need to fill in two elements on - the form: - * The `CERTIFY_SAFE` box should be checked. By checking it, you are - indicating that you have reviewed the code you are about to test and you - are confident that it does not contain any malicious code. (We don't want - people hijacking our CI hosts to attack other hosts on the internet, for - example!) - * The `PR_ID` box should be filled in with the number identifying the pull - request containing the code you wish to test. For example, if the URL for - the pull request is `https://github.com/nodejs/node/issues/7006`, then put - `7006` in the `PR_ID`. - * The remaining elements on the form are typically unchanged. - * If you need help with something CI-related: - * Use the [Build WG repository](https://github.com/nodejs/build) to file - issues for the Build WG members who maintain the CI infrastructure. + * Two collaborator approvals are required before a pull request can land (one + is enough if the pull request has been open for more than 7 days). See + [GOVERNANCE.md][the collaborators team]. ## Landing pull requests -See the Collaborator Guide: [Landing pull requests][]. - -For our versioning conventions, tagging strategy, stability flows, and semantic versioning rules, refer to our [Release Management & Tagging Strategy][Release Management] guide. - -Commits in one pull request that belong to one logical change should -be squashed. It is rarely the case in onboarding exercises, so this -needs to be pointed out separately during the onboarding. - - - -## Exercise: Make a pull request adding yourself to the README - -* Example: - - * For raw commit message: - `git show --format=%B 6669b3857f0f43ee0296eb7ac45086cd907b9e94` -* Collaborators are in alphabetical order by GitHub username. -* Optionally, include your personal pronouns. -* Commit, including a `Fixes: ` trailer - so that when the commit lands, the nomination issue url will be - automatically closed. -* Run `tools/find-inactive-collaborators.mjs`. If that command outputs your name, - amend the commit to include an addition to the [mailmap](.mailmap) file. See - [gitmailmap](https://git-scm.com/docs/gitmailmap) for information on the - format of the mailmap file. -* Push the commit to your own fork. -* Label your pull request with the `doc`, `notable-change`, and `fast-track` - labels. The `fast-track` label should cause the SurveyDesigner GitHub bot to post a - comment in the pull request asking collaborators to approve the pull request - by leaving a πŸ‘ reaction on the comment. -* Optional: Run Jenkins CI on the pull request. Use the [`node-test-pull-request`][] - task. As a convenience, you may apply the `request-ci` label to the pull - request to have a GitHub Actions workflow start the Jenkins CI task for you. -* After two Collaborator approvals for the change and two Collaborator approvals - for fast-tracking, land the PR. If you have started a full Jenkins CI, cancel it - from the Jenkins UI since the PR is a doc-only change and does not need - a full CI run, it is just run as an exercise. -* If there are not enough approvals within a reasonable time, consider the - single approval of the onboarding TSC member sufficient, and land the pull - request. - * Be sure to add the `PR-URL: ` and appropriate `Reviewed-By:` - metadata. - * [`@node-core/utils`][] automates the generation of metadata and the landing - process. See the documentation of [`git-node`][]. - * [`core-validate-commit`][] automates the validation of commit messages. - This will be run during `git node land --final` of the [`git-node`][] - command. - * Normally you can just use the `commit-queue` label to have the - commit queued for landing by the Node.js GitHub bot. But as exercise it is - also useful to learn how to land commits manually in case the bot or the CI - is broken. -* If you are landing the commit manually, to make it appear as "Merged" on GitHub, - after you prepare the landed commit on the local `main` branch, run this: - - ```bash - git push --force-with-lease your-fork-remote HEAD:your-pr-branch # Update the PR branch in your fork. - git push upstream main # Push the landed commit to the upstream main branch. - ``` - - GitHub will automatically detect that the PR branch is now identical to the - `main` branch and will mark the PR as "Merged". +* We use a **monorepo** with **trunk-based development**. All feature and bug + fix branches target `main` and should be short-lived. +* Commits in one pull request that belong to one logical change should be + squashed before landing. +* Ensure the pull request description links the relevant GitHub issue. +* For our versioning conventions, tagging strategy, and semantic versioning + rules, refer to the [Release Management & Tagging Strategy][Release Management]. ## Final notes * Don't worry about making mistakes: everybody makes them, there's a lot to - internalize and that takes time (and we recognize that!) + internalize and that takes time (and we recognize that!). * Almost any mistake you could make can be fixed or reverted. * The existing collaborators trust you and are grateful for your help! -* Other repositories: - * : Governance discussions and TSC votes - * : Build infrastructure discussions and CI issues - * : The Node.js website and blog - * : Release management and release planning - * : Tool for testing popular packages against Node.js changes - * : Administrative issues and requests to changes in the Node.js - GitHub organization (e.g. creating new repositories, new teams, adding organization-wide tokens). - * : Requests to moderate comments or block spammers. -* The OpenJS Foundation hosts regular summits for active contributors to the - Node.js project, where we have face-to-face discussions about our work on the - project. The Foundation has travel funds to cover [participants' expenses][] - including accommodations, transportation, and visa fees (even in case the visa - is denied) if needed. Check out the [summit](https://github.com/nodejs/summit) - repository for details. -* If you are interested in helping to fix coverity reports consider requesting - access to the projects coverity project as outlined in [static-analysis][]. -* If you are interested in helping out with CI reliability, check out the - [reliability respository][] and [guide on how to deal with CI flakes][]. - -[Code of Conduct]: https://github.com/nodejs/admin/blob/HEAD/CODE_OF_CONDUCT.md -[Labels]: doc/contributing/collaborator-guide.md#labels -[Landing pull requests]: doc/contributing/collaborator-guide.md#landing-pull-requests -[Publicizing or hiding organization membership]: https://help.github.com/articles/publicizing-or-hiding-organization-membership/ -[`@node-core/utils`]: https://github.com/nodejs/node-core-utils -[`author-ready`]: doc/contributing/collaborator-guide.md#author-ready-pull-requests -[`core-validate-commit`]: https://github.com/nodejs/core-validate-commit -[`git-node`]: https://github.com/nodejs/node-core-utils/blob/HEAD/docs/git-node.md -[`node-test-pull-request`]: https://ci.nodejs.org/job/node-test-pull-request/ -[guide on how to deal with CI flakes]: https://github.com/nodejs/test?tab=readme-ov-file#protocols-in-improving-ci-reliability -[participants' expenses]: https://github.com/openjs-foundation/cross-project-council/blob/main/community-fund/COMMUNITY_FUND_POLICY.md#community-fund-rules -[reliability respository]: https://github.com/nodejs/reliability -[set up the credentials]: https://github.com/nodejs/node-core-utils#setting-up-github-credentials -[static-analysis]: doc/contributing/static-analysis.md -[two-factor authentication]: https://help.github.com/articles/securing-your-account-with-two-factor-authentication-2fa/ -[using a TOTP mobile app]: https://help.github.com/articles/configuring-two-factor-authentication-via-a-totp-mobile-app/ -[who-to-cc]: doc/contributing/collaborator-guide.md#who-to-cc-in-the-issue-tracker -[the collaborators team]: GOVERNANCE.md -[subsystem teams]: GOVERNANCE.md -[WFP Slack Community]: https://wfp.slack.com/ -[a bot]: https://github.com/nodejs-github-bot/github-bot -[Technical Values]: doc/contributing/TECHNICAL_VALUES.md +* The project has a venue for real-time discussion on the + [WFP Slack Community][], and asynchronous discussion in + [GitHub Discussions][]. + +[CONTRIBUTING.md]: CONTRIBUTING.md +[Code of Conduct]: CODE_OF_CONDUCT.md +[GitHub Discussions]: https://github.com/wfp/surveydesigner/discussions +[Issue Hierarchy Validator]: ../.github/workflows/issue-hierarchy-validator.yml +[Moderation Policy]: MODERATION_POLICY.md +[Publicizing or hiding organization membership]: https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/publicizing-or-hiding-organization-membership [Release Management]: doc/contributing/RELEASE_MANAGEMENT.md +[Technical Values]: doc/contributing/TECHNICAL_VALUES.md +[WFP Slack Community]: https://wfp.slack.com/ +[e2e readme]: ../react-ui/e2e/README.md +[issue templates]: ../.github/ISSUE_TEMPLATE +[moderation members]: MODERATION_POLICY.md#current-members-of-moderation-team +[the collaborators team]: GOVERNANCE.md#collaborators +[two-factor authentication]: https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..07077c5 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,62 @@ +# Survey Designer Documentation + +Welcome! This directory contains the contributor, governance, and process +documentation for the **Survey Designer** project β€” an application for building +XLSForm/ODK-based surveys while maintaining WFP standard labeling and naming +conventions. + +Survey Designer is a **decoupled monorepo**: + +* `react-ui/` β€” React 18 + TypeScript frontend built with Vite, tested with + Vitest and Playwright. +* `dj-be/` β€” Django 5.2 backend (REST API + Django admin) with PostgreSQL, + Redis, MinIO, and Keycloak, tested with pytest. + +For product setup and how to run the application, see the +[repository README](../README.md). + +## Getting started as a contributor + +| Document | What it covers | +| :--- | :--- | +| [CONTRIBUTING.md](CONTRIBUTING.md) | Contribution workflow, branch naming, testing and security requirements, license compliance. | +| [BUILDING.md](BUILDING.md) | How to build the frontend artifact and the backend Docker image. | +| [ONBOARDING.md](ONBOARDING.md) | Local setup for both apps, running tests and Playwright e2e, and what new collaborators are expected to know. | +| [Technical Values & Development Principles](doc/contributing/TECHNICAL_VALUES.md) | Architecture, trunk-based development, environments, engineering values, testing, and coverage requirements. | +| [Release Management & Tagging Strategy](doc/contributing/RELEASE_MANAGEMENT.md) | Semantic Versioning, Git tagging rules, release paths, and the release workflow. | + +## Governance and community + +| Document | What it covers | +| :--- | :--- | +| [GOVERNANCE.md](GOVERNANCE.md) | Roles (triagers, collaborators, the maintainers team), nominations, decision-making, and the consensus-seeking process. | +| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Expected behavior and enforcement guidelines. | +| [MODERATION_POLICY.md](MODERATION_POLICY.md) | How moderation requests are made and handled. | +| [Working Groups](WORKING_GROUPS.md) | How focused working groups are chartered and operate. | +| [Roadmap Guidance](doc/ROADMAP_GUIDANCE.md) | How the roadmap is tracked and how to propose items. | + +## Testing and quality at a glance + +Every change must pass the checks below before it can be merged. Full details +are in [CONTRIBUTING.md](CONTRIBUTING.md) and +[Technical Values](doc/contributing/TECHNICAL_VALUES.md). + +| Area | Command | Tooling | +| :--- | :--- | :--- | +| Frontend unit tests + coverage | `pnpm test:ci` | Vitest + `@vitest/coverage-v8` | +| Frontend lint / format / types | `pnpm lint`, `pnpm pretty`, `pnpm tsc` | ESLint, Prettier, TypeScript | +| Backend tests + coverage | `docker compose run api test-ci` (or `make test`) | pytest + pytest-cov | +| End-to-end | `pnpm e2e:ci` | Playwright (see [`react-ui/e2e/README.md`](../react-ui/e2e/README.md)) | + +> [!IMPORTANT] +> **Branch coverage must be greater than 85%.** Coverage is measured with +> branch coverage enabled (`branch = True` for the backend, `@vitest/coverage-v8` +> for the frontend). See +> [Technical Values β†’ Test Automation & CI Compliance](doc/contributing/TECHNICAL_VALUES.md#test-automation--ci-compliance) +> for details and the current configuration status. + +## Reporting security issues + +Do **not** open a public issue for security vulnerabilities. Email +**global.surveydesigner@wfp.org** β€” see the Security Protocol in +[CONTRIBUTING.md](CONTRIBUTING.md#-security-protocol). diff --git a/docs/WORKING_GROUPS.md b/docs/WORKING_GROUPS.md new file mode 100644 index 0000000..8513ed1 --- /dev/null +++ b/docs/WORKING_GROUPS.md @@ -0,0 +1,42 @@ +# Working Groups + +Working Groups (WGs) are collections of collaborators who take responsibility +for a specific, ongoing area of the Survey Designer project. They allow focused +work to proceed without requiring the whole maintainers team to be involved in +every decision. + +## Purpose + +* Concentrate expertise and responsibility for a defined area (for example, + frontend, backend/API, documentation, or release engineering). +* Give contributors a clear place to participate and be notified about work in + their area of interest. +* Reduce the decision-making load on the maintainers team by delegating autonomy + for day-to-day matters within the group's scope. + +## Authority + +Working Groups derive their authority from the maintainers team. A Working Group +has autonomy over the area delegated to it, within the boundaries agreed with +the maintainers team. The maintainers team retains final authority as described +in [GOVERNANCE.md](GOVERNANCE.md#the-surveydesigner-maintainers-team) and +may create, modify, or dissolve a Working Group. + +## Lifecycle + +1. **Chartering** β€” A collaborator proposes a Working Group by opening an issue + describing its scope, initial members, and the responsibilities being + delegated. The proposal follows the maintainers team's + [consensus-seeking process](GOVERNANCE.md#consensus-seeking-process). +2. **Operating** β€” The Working Group carries out its responsibilities, reviews + and lands pull requests within its scope (following the two-approval rule in + [GOVERNANCE.md](GOVERNANCE.md#collaborators)), and reports to the + maintainers team as agreed. +3. **Dissolution** β€” When a Working Group's scope is complete or no longer + active, the maintainers team may dissolve it and, if appropriate, fold its + responsibilities back into the collaborator body. + +## Current Working Groups + +No Working Groups are chartered yet. When the first Working Group is created, +list it here with its scope and a link to its tracking issue or team. diff --git a/docs/doc/ROADMAP_GUIDANCE.md b/docs/doc/ROADMAP_GUIDANCE.md index 95344bf..e902f42 100644 --- a/docs/doc/ROADMAP_GUIDANCE.md +++ b/docs/doc/ROADMAP_GUIDANCE.md @@ -1 +1,43 @@ -See https://github.com/github/roadmap?tab=readme-ov-file +# Roadmap Guidance + +The Survey Designer roadmap communicates the direction of the project: what the +maintainers intend to work on, in what rough order, and why. It helps +contributors and users understand where the project is heading and where they +can help. + +## Where the roadmap lives + +The roadmap is tracked through the project board in the WFP GitHub +organization: + +* [Survey Designer project board](https://github.com/orgs/wfp/projects/11) + +Issues on the board follow the hierarchy enforced by the +[Issue Hierarchy Validator](../../.github/workflows/issue-hierarchy-validator.yml) +workflow: **Epic β†’ Feature β†’ User Story β†’ Task**. Roadmap-level planning is +expressed primarily through Epics and Features. + +## How items get onto the roadmap + +1. Ideas are captured as issues using the templates in + [`.github/ISSUE_TEMPLATE`](../../.github/ISSUE_TEMPLATE) (Epic, Feature, + User Story, Task, Bug). +2. Larger initiatives are grouped under an Epic, broken down into Features and + User Stories, and prioritized on the project board. +3. Direction and prioritization are set by the collaborators and, for matters at + an impasse, by the SurveyDesigner maintainers team following the + [consensus-seeking process](../GOVERNANCE.md#consensus-seeking-process). + +## Relationship to releases + +Roadmap delivery is reflected in releases, which follow the +[Release Management & Tagging Strategy](contributing/RELEASE_MANAGEMENT.md). +Major roadmap milestones typically correspond to `MINOR` or `MAJOR` version +increments under Semantic Versioning. + +## Contributing to the roadmap + +Anyone may propose roadmap items by opening an issue and, optionally, raising it +for discussion in [GitHub Discussions](https://github.com/wfp/surveydesigner/discussions) +or the [WFP Slack Community](https://wfp.slack.com/). See +[CONTRIBUTING.md](../CONTRIBUTING.md) for the full contribution workflow. diff --git a/docs/doc/TSC/TSC_CHARTER.md b/docs/doc/TSC/TSC_CHARTER.md deleted file mode 100644 index ffd0b8f..0000000 --- a/docs/doc/TSC/TSC_CHARTER.md +++ /dev/null @@ -1,3 +0,0 @@ -# Technical Steering Committee (TSC) Charter - -## Section 1. Guiding Principle diff --git a/docs/doc/TSC/WORKING_GROUPS.md b/docs/doc/TSC/WORKING_GROUPS.md deleted file mode 100644 index 8b13789..0000000 --- a/docs/doc/TSC/WORKING_GROUPS.md +++ /dev/null @@ -1 +0,0 @@ - diff --git a/docs/doc/TSC/voting/README.md b/docs/doc/TSC/voting/README.md deleted file mode 100644 index 8b13789..0000000 --- a/docs/doc/TSC/voting/README.md +++ /dev/null @@ -1 +0,0 @@ - diff --git a/docs/doc/contributing/TECHNICAL_VALUES.md b/docs/doc/contributing/TECHNICAL_VALUES.md index 7f1b608..e47b867 100644 --- a/docs/doc/contributing/TECHNICAL_VALUES.md +++ b/docs/doc/contributing/TECHNICAL_VALUES.md @@ -14,10 +14,12 @@ Survey Designer is built around a modern, scalable, and decoupled architecture d graph TD subgraph Client-Side (Local Runtime) React[ReactJS + Vite SPA] + I18n[i18next locales] end subgraph Service-Side (Docker Containerized) Backend[Django Backend] + Worker[RQ Worker] DB[(PostgreSQL)] Cache[(Redis Cache)] Storage[(MinIO Storage)] @@ -25,11 +27,20 @@ graph TD Mail[Maildev SMTP] end + subgraph Build-Time Tooling + TransCLI[translationcli.py + deep_translator] + end + React <-->|REST APIs / JSON| Backend + React --> I18n Backend <--> DB Backend <--> Cache Backend <--> Storage - Backend <--> Auth + Backend <-->|OIDC| Auth + Backend <--> Mail + Worker <--> Cache + Auth <--> DB + TransCLI -->|generates locale JSON| I18n ``` ### Decoupled Architecture @@ -40,6 +51,69 @@ graph TD * **Single Source of Truth:** Both the frontend (`react-ui`) and backend (`dj-be`) reside in a single repository. This enables atomic commits across layers, facilitates co-dependent changes, and simplifies repository discovery. * **Unified Tooling & Guidelines:** All documentation, licensing, security protocols, and shared developer environments are consolidated, simplifying onboarding and ensuring compliance. +### Full Service Topology +The backend stack is orchestrated by `dj-be/docker-compose.yml`. Each service +has a distinct responsibility and a documented reason for being part of the +architecture. + +| Service | Image / Tech | Local Port | Responsibility | Why it is used | +| :--- | :--- | :--- | :--- | :--- | +| `api` | Django 5.2 + DRF | `8080` | REST API, Django admin, static assets | Core application runtime and single API surface for the SPA. | +| `worker` | Django RQ | β€” | Background/async jobs off the request path | Keeps long-running work (e.g. generation, e-mail) out of the request cycle. | +| `postgres` | `postgres:16` | `5432` | Primary datastore for the app **and** Keycloak | A single managed relational store; a dedicated `keycloak` DB is created by `init-keycloak-db.sh` to isolate IDP data. | +| `redis` | `redis:6` | β€” | Cache and RQ broker | Fast cache plus the queue backend the worker consumes. | +| `minio` | MinIO (S3-compatible) | `9000`/`9001` | Object storage for media uploads | Local, S3-compatible storage so file handling matches production S3 without an AWS dependency. | +| `keycloak` | `quay.io/keycloak/keycloak:22.0.1` | `8081` | Identity Provider (OIDC) | Externalizes authentication so the app never stores credentials itself (see Authentication below). | +| `maildev` | `maildev/maildev` | `1080` | Local SMTP + web mail inbox | Lets developers exercise transactional e-mail flows without sending real mail. | + +### Authentication: Keycloak & OIDC +Authentication is delegated to **Keycloak** over **OpenID Connect (OIDC)**; +the application never manages passwords directly. + +* **Container:** The `keycloak` service runs `start-dev` on `:8081` with a + Postgres backend (`KC_DB=postgres`, database `keycloak`). The default + bootstrap admin is `admin` / `admin` for local development only. +* **Pluggable provider:** `survey_designer/settings.py` selects the auth + backend from the `IDENTITY_PROVIDER` environment variable. The default is + `core.auth.backends.OIDCAuthenticationBackend` (Keycloak); setting + `IDENTITY_PROVIDER=CIAM` switches to + `core.auth.backends.OIDCAuthenticationBackendCIAM`. +* **Configuration:** The OIDC integration is driven entirely by environment + variables (see `dj-be/.env.sample`): + `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`, `OIDC_ENDPOINT` (token introspection), + `OIDC_AUTHORIZATION_ENDPOINT`, `OIDC_TOKEN_ENDPOINT`, `OIDC_JWKS_ENDPOINT`, + `OIDC_CONFIGURATION_ENDPOINT`, `OIDC_USERINFO_ENDPOINT`, and + `OIDC_CALLBACK_URL`. These point at a realm such as + `https://keycloak.domain.org/realms/survey-designer/...`. +* **Why Keycloak / OIDC is used:** It provides standards-based SSO, keeps + credential handling out of the application, and β€” through the pluggable + backend β€” lets the same codebase authenticate against either a + self-hosted Keycloak realm or WFP's CIAM without code changes. + +### Localization Pipeline (i18next + `translationcli.py`) +Multi-language support is handled **on the frontend** and the translation files +live in the repository β€” there is no runtime translation service. + +* **Runtime:** The SPA uses **i18next** (`react-ui/src/locales/i18n.ts`) with + `i18next-http-backend` and `i18next-browser-languagedetector`. English is the + `fallbackLng`. Supported locales: `en`, `es`, `fr`, `ar`, `pt`, `ru`, each + with its own `translations.json`. +* **Source of truth:** `en/translations.json` is authored by hand. Every other + locale is generated from it. +* **Generation:** `pnpm translate` (see `react-ui/package.json`) installs + `deep_translator` + `tabulate` and runs `dj-be/translationcli.py`, which loads + the English JSON and, using `deep_translator`'s `GoogleTranslator`, + recursively translates every string into each language in + `CURRENT_SUPPORTED_LANGUAGES`, writing one `translations.json` per locale. + The script then runs `pnpm run build`. +* **Why this approach is used:** Keeping locale JSON in-repo means translations + are versioned, reviewable in pull requests, and shipped as static assets with + the build β€” no external translation platform or network dependency at + runtime. Machine translation via `translationcli.py` gives contributors a + fast, zero-cost baseline for all supported languages from a single + hand-maintained English source, which can then be refined by hand where + needed. + --- ## πŸ”„ 2. Trunk-Based Development (TBD) @@ -104,6 +178,36 @@ No code should be merged without validation. Run tests locally prior to pushing | :--- | :--- | :--- | | **Frontend** | `pnpm test:ci` | Vitest / Testing Library | | **Backend** | `docker compose run api test-ci` | Django Unit Tests / Pytest | +| **End-to-end** | `pnpm e2e:ci` | Playwright (real Django stack) | + +#### Branch Coverage Requirement + +> [!IMPORTANT] +> **Branch coverage must be greater than 85%** for every change. Coverage is +> collected with *branch* coverage enabled so that both sides of each +> conditional are exercised, not just line coverage. + +* **Frontend:** `pnpm test:ci` runs `vitest run --coverage` using + `@vitest/coverage-v8`. Coverage is reported to the `coverage/` directory + (`text` and `cobertura` reporters). +* **Backend:** `pytest` runs with `--cov survey_designer` and `branch = True` + (see `dj-be/setup.cfg`), producing XML, HTML, and terminal reports. + +> [!WARNING] +> **Current configuration does not yet enforce the 85% target automatically.** +> At present the backend gate is `--cov-fail-under 70` in `dj-be/setup.cfg`, and +> the frontend (`react-ui/vite.config.js`) sets no coverage threshold at all. +> Until these are aligned, reviewers must verify the 85% branch-coverage +> requirement manually. To enforce it automatically, raise the backend gate to +> `--cov-fail-under 85` and add a Vitest `coverage.thresholds` block (for +> example `{ branches: 85 }`). Changing these gates can cause currently passing +> pipelines to fail if existing coverage is below 85%, so coordinate the change +> with the maintainers. + +* **End-to-end:** Playwright drives the frontend against the real local Django + stack (the API is not mocked). See + [`react-ui/e2e/README.md`](../../../react-ui/e2e/README.md) for setup, + authentication via `POST /auth/e2e-login/`, and CI details. ### GNU AGPL-3.0 License Compliance Survey Designer is open-source software licensed under the **GNU Affero General Public License v3**. @@ -114,7 +218,7 @@ Survey Designer is open-source software licensed under the **GNU Affero General ### Security-First Defaults * **Secure Communications:** Standardized authentication via **Keycloak (OIDC)** is integrated into the core login flow. * **Vulnerability Scanning:** Security checks (e.g., Trivy container scans) are periodically run to identify and resolve CVEs early. -* **Vulnerability Disclosure:** In the event of a security discovery, do **not** open a public issue. Email the details directly to **leandro.bravo@wfp.org**. +* **Vulnerability Disclosure:** In the event of a security discovery, do **not** open a public issue. Email the details directly to **global.surveydesigner@wfp.org**. ---