From 0b56f8956a74d93c647b7e82f1bdfa950ac86821 Mon Sep 17 00:00:00 2001 From: Pramod Kandel Date: Sun, 27 Sep 2026 22:57:46 +0545 Subject: [PATCH] docs: establish contribution foundations Signed-off-by: Pramod Kandel --- .github/ISSUE_TEMPLATE/bug.yml | 35 + .github/ISSUE_TEMPLATE/config.yml | 8 + .github/ISSUE_TEMPLATE/design.yml | 35 + .github/ISSUE_TEMPLATE/task.yml | 53 ++ .github/ISSUE_TEMPLATE/translation.yml | 27 + .github/pull_request_template.md | 7 + .gitignore | 2 + CODE_OF_CONDUCT.md | 59 ++ CONTRIBUTING.md | 113 ++++ GOVERNANCE.md | 37 ++ LICENSE | 201 ++++++ MAINTAINERS.md | 13 + PRIVACY.md | 87 +++ README.md | 2 + README.ne.md | 98 +++ SECURITY.md | 49 ++ docs/CONVENTIONS.md | 138 ++++ docs/PRD-v0.1.md | 228 +++++++ docs/PRD.md | 847 +++++++++++++++++++++++++ 19 files changed, 2039 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/design.yml create mode 100644 .github/ISSUE_TEMPLATE/task.yml create mode 100644 .github/ISSUE_TEMPLATE/translation.yml create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 GOVERNANCE.md create mode 100644 LICENSE create mode 100644 MAINTAINERS.md create mode 100644 PRIVACY.md create mode 100644 README.ne.md create mode 100644 SECURITY.md create mode 100644 docs/CONVENTIONS.md create mode 100644 docs/PRD-v0.1.md create mode 100644 docs/PRD.md diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml new file mode 100644 index 0000000..1b14f5f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -0,0 +1,35 @@ +name: Bug +description: Something is not working +labels: [bug] +body: + - type: markdown + attributes: + value: "**Security problem?** Do not use this form — follow the private reporting instructions in [SECURITY.md](https://github.com/SDOC-Team/devnepal/blob/main/SECURITY.md)." + - type: textarea + id: what-happens + attributes: { label: What happens } + validations: { required: true } + - type: textarea + id: expected + attributes: { label: What should happen } + validations: { required: true } + - type: textarea + id: steps + attributes: + label: Steps to reproduce + value: | + 1. + 2. + validations: { required: true } + - type: dropdown + id: language + attributes: + label: Language + options: ["English", "नेपाली", "Both"] + - type: input + id: environment + attributes: + label: Browser and device + - type: markdown + attributes: + value: "Please do not include real personal data, credentials, or production records." diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..40618eb --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: true +contact_links: + - name: Report a security vulnerability + url: https://github.com/SDOC-Team/devnepal/blob/main/SECURITY.md + about: Never report security issues publicly. Check the policy for private reporting availability + - name: Code of conduct concern + url: https://github.com/SDOC-Team/devnepal/blob/main/CODE_OF_CONDUCT.md + about: Check the policy for private contact availability. Do not post confidential reports in public issues diff --git a/.github/ISSUE_TEMPLATE/design.yml b/.github/ISSUE_TEMPLATE/design.yml new file mode 100644 index 0000000..355cf47 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/design.yml @@ -0,0 +1,35 @@ +name: Design or accessibility +description: Propose an interface improvement or report an accessibility problem +labels: [design] +body: + - type: markdown + attributes: + value: | + Icons, accessibility fixes, typography and content are open now. + The core visual language is being settled by the design team — we will open it once the design system is published. + - type: textarea + id: problem + attributes: + label: What is the problem for a user? + validations: { required: true } + - type: textarea + id: existing + attributes: + label: Which existing pattern is inadequate, and why? + - type: textarea + id: proposal + attributes: + label: Proposal + description: Screenshot, link, or description. + validations: { required: true } + - type: textarea + id: bilingual + attributes: + label: How does this work in both languages? + description: Required. Devanagari has different line-height and width behaviour from Latin. + validations: { required: true } + - type: textarea + id: a11y + attributes: + label: Accessibility + description: Keyboard operation, focus order, contrast. diff --git a/.github/ISSUE_TEMPLATE/task.yml b/.github/ISSUE_TEMPLATE/task.yml new file mode 100644 index 0000000..7e138c4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/task.yml @@ -0,0 +1,53 @@ +name: Task +description: A well-scoped piece of work ready for a contributor +body: + - type: textarea + id: context + attributes: + label: Context + description: Two to four sentences. Why does this exist, who does it serve? Assume no prior knowledge of this project. + validations: { required: true } + - type: textarea + id: in-scope + attributes: + label: In scope + validations: { required: true } + - type: textarea + id: out-of-scope + attributes: + label: Out of scope + description: Be explicit. This field prevents most oversized pull requests and protects your time. + validations: { required: true } + - type: textarea + id: acceptance + attributes: + label: Acceptance criteria + value: | + - [ ] + - [ ] + validations: { required: true } + - type: textarea + id: where + attributes: + label: Where to look + description: Files and modules involved, and an existing example to copy the pattern from. + validations: { required: true } + - type: textarea + id: tests + attributes: + label: Tests expected + description: Describe automated tests or manual verification. If none apply, explain why. + validations: { required: true } + - type: dropdown + id: size + attributes: + label: Size + options: ["S — under 4 hours", "M — 4 to 16 hours", "L — 16 to 40 hours"] + validations: { required: true } + - type: input + id: mentor + attributes: + label: Mentor + description: Who will answer questions on this issue + placeholder: "@username" + validations: { required: true } diff --git a/.github/ISSUE_TEMPLATE/translation.yml b/.github/ISSUE_TEMPLATE/translation.yml new file mode 100644 index 0000000..adfa230 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/translation.yml @@ -0,0 +1,27 @@ +name: Nepali translation or content +description: Improve Nepali wording, terminology, or English microcopy +labels: [i18n, nepali-language] +body: + - type: markdown + attributes: + value: "This is one of the most valuable kinds of contribution here, and it needs no code." + - type: input + id: where + attributes: + label: Where is it? + placeholder: "Page, or the string key" + validations: { required: true } + - type: textarea + id: current + attributes: { label: Current wording } + validations: { required: true } + - type: textarea + id: suggested + attributes: { label: Suggested wording } + validations: { required: true } + - type: textarea + id: why + attributes: + label: Why is this better? + description: Register, accuracy, clarity, or common usage. + validations: { required: true } diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 29c5840..44b6a29 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -18,3 +18,10 @@ ## Notes for reviewers + +## Foundation checklist + +- [ ] Commits signed off (`git commit -s`) +- [ ] Works in **both** English and Nepali where applicable +- [ ] No secrets or real personal data anywhere in the diff +- [ ] Documentation updated; English and Nepali versions agree where both exist diff --git a/.gitignore b/.gitignore index e937b55..7134116 100644 --- a/.gitignore +++ b/.gitignore @@ -36,3 +36,5 @@ coverage/ # Agent instructions that `next dev` regenerates /apps/api/AGENTS.md /apps/api/CLAUDE.md +.claude/ +.codex/ diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..25c3ee6 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,59 @@ +# Code of Conduct + +## Our commitment + +devNepal is a public space serving the people of Nepal. Everyone participating is entitled to a harassment-free experience regardless of background, identity, experience level, employment status, or first language. + +--- + +## Expected + +- Treat people with respect, including — especially — in disagreement +- Assume good faith. Ask before assuming error +- Welcome first-time contributors. Everyone was one +- Accept review feedback gracefully, and give it kindly +- Respect that English is not everyone's first language, and that Nepali is not everyone's either + +--- + +## Not acceptable + +- Harassment, intimidation, or discriminatory language +- Personal or political attacks +- Publishing another person's private information +- Sustained disruption of discussion +- **Impersonating another person or organisation**, including claiming an affiliation you do not hold +- Unwelcome attention of any kind + +--- + +## Reporting + +**Private reporting contact:** not yet published. Do not put confidential reports in public issues. + +We will: + +- Acknowledge within 48 hours +- Keep the report confidential, sharing only with those who need to act +- Tell you what action was taken + +**You will never be penalised for a good-faith report**, including a report about a maintainer or a government team member. + +--- + +## Enforcement + +In proportion, and always with a recorded reason: + +1. **Private correction** — a clarification of what was expected +2. **Public warning** +3. **Temporary suspension** from participation +4. **Permanent ban** + +Decisions may be appealed privately and must be reviewed by someone not involved in the original decision. An appeal contact has not yet been published. + +--- + +## Scope + +This applies to this repository, the devNepal portal, and any space where someone is representing the project. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..2b50980 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,113 @@ +# Contributing to devNepal + +Thank you. This is a public service built in public, and outside contribution is the point rather than a bonus. + +**This page explains how we work together.** Branch names, commit format, labels, and the checklists for a ready issue and a finished pull request are in **[docs/CONVENTIONS.md](./docs/CONVENTIONS.md)** — read it once, then look things up as you need them. + +--- + +## What we commit to + +| | | +|---|---| +| First response to a pull request or issue | **Within 3 days** | +| Security report acknowledgement | **Within 24 hours** | + +Days are calendar days. Most of us do this outside a day job, so review happens in short windows through the week plus one longer session at the weekend. + +If we are ever at capacity we will say so publicly and pause new claims, rather than going quiet. + +--- + +## Before you start + +**Only claim issues labelled `ready`. Comment on the issue to claim it.** We will assign it to you. If nothing suitable is ready, open a proposal or ask for clarification before starting. + +After 14 days without activity, maintainers will check in and may manually unassign the issue, leaving an explanation. This is never a judgement on you — claim it again whenever you are ready. + +**Open an issue before large or design work.** A proposal that arrives as a finished artifact has already cost you a weekend, and we would rather agree the problem with you first. + +--- + +## How to contribute code + +1. Fork the repository, branch from `main` +2. Make your change. **One issue per pull request** +3. **Sign off every commit**: `git commit -s` +4. Open a pull request referencing the issue + +Branch naming, commit message format and pull-request size guidance are in **[docs/CONVENTIONS.md](./docs/CONVENTIONS.md)**. + +Draft pull requests are welcome early. Reviewing direction at 20% complete costs everyone less than reviewing at 100%. + +--- + +## Sign-off (DCO) + +Every commit needs a `Signed-off-by` line, which `git commit -s` adds from your git configuration. Use `-s` on every commit. + +It certifies that you wrote the contribution, or that you have the right to submit it under this project's licence. It is **not** a copyright assignment — you keep the copyright in your work, and there is no separate agreement to sign. + +Full text: + +--- + +## Licensing + +devNepal is released under the Apache License 2.0. By submitting a contribution you agree it is licensed to the project under those same terms. + +You retain copyright in your contribution. We do not ask you to assign or transfer it. + +--- + +## Contribution is not only code + +Design, Nepali translation, documentation, testing, accessibility and security work are all reviewed and credited the same way as code. If you want to contribute to an area not on that list, open an issue and ask — the list grows as the people who can review it arrive. + +If you improve a Nepali error message or find a contrast failure, you have contributed. Tell us and we will credit it. + +**On design work specifically:** The core visual language is being settled by the design team while the system is established — we will say so when that changes. + +--- + +## What we look for + +- Works in **both** English and Nepali +- Accessible: keyboard operable, visible focus, sufficient contrast +- Uses design tokens — never hard-coded colours or spacing +- Tests for behaviour changes +- **No new dependency without agreeing it in the issue first.** This is a government supply chain + +The full definition of done, and what makes an issue safe to claim, are in [docs/CONVENTIONS.md](./docs/CONVENTIONS.md). + +--- + +## Review + +Reviews name the specific change requested, never a vague dissatisfaction. + +A comment prefixed `Nit:` is a preference and never blocks a merge. + +**If we decline a pull request on direction, we will explain what would have been accepted.** You spent hours; three sentences of explanation is the minimum owed. + +If we take over a pull request, you keep the credit and we will tell you why. + +--- + +## Security + +**Never report a vulnerability in a public issue or pull request.** See [SECURITY.md](./SECURITY.md). + +If you find a security problem while working on something unrelated, stop and report it privately. A public fix is a public disclosure. + +--- + +## Language + +Issues, pull requests and reviews may be in English or Nepali. Say so if you would prefer Nepali and we will switch. + +--- + +## Who merges + +Maintainers — who may be from outside government — review and approve. **Merge and deployment are performed by the government team.** This is a deliberate boundary, described in [GOVERNANCE.md](./GOVERNANCE.md). diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 0000000..0eda406 --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,37 @@ +# Governance + +## The short version + +**The government department that owns a system decides what it must do. The technical team decides how it is built. The community contributes the work and the scrutiny. Merge and deployment are government-only.** + +--- + +## Roles + +| Role | Who | Decides | Does not decide | +|---|---|---|---| +| **Steering** | Office of the Prime Minister | Which projects enter the devNepal programme; funding; approval to deploy to production | What any individual system must do; technical design; individual pull requests | +| **Sponsoring department** | The ministry or body that owns a given system. **For this portal, the Office of the Prime Minister** | What that system must do; acceptance of completed work | How it is built; who may contribute; when it deploys | +| **Core team** | Government-employed or contracted engineers | Architecture, stack, merge, release, deployment, security posture | What a system must do | +| **Maintainers** | Appointed by the core team, **and may be from outside government** | Review and approval of pull requests in their area; triage; mentoring | Merge to `main`; deployment; releases | +| **Contributors** | Anyone | What they work on, from the open backlog | — | + +--- + +## Maintainers, and how you become one + + +| Level | Who | What they can do | +|---|---|---| +| **Contributor** | Anyone | Propose changes, comment, review informally | +| **Maintainer** | Appointed by the core team. **May be from outside government** | Binding approval of pull requests in their area | +| **Core** | Government appointment or contract | Merge, release, deploy | + + +**What comes next.** Once there is a body of contributors with a real track record, we will publish criteria for moving from contributor to maintainer — a promotion path, rather than appointment — and start promoting from contribution. The criteria will be stated plainly rather than left to judgement. + +**What holds regardless:** + +- Maintainers may be non-government. **Nobody outside government merges or deploys** +- Authority is area-scoped — a maintainer of the design system has no authority over authentication +- We would rather give you review authority than keep reviewing everything ourselves. If you are contributing consistently in one area, ask where you stand and we will tell you plainly diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..a36e57e --- /dev/null +++ b/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2026 Government of Nepal, Office of the Prime Minister + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 0000000..f89a397 --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,13 @@ +# Maintainers + +Individual area contacts have not yet been published. For non-confidential questions, open an issue. For sensitive reports, follow [SECURITY.md](./SECURITY.md) or [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md). + +| Area | Maintainer | Responds on | +|---|---|---| +| Portal — views, models, routing | Not yet published | Issues labelled `area/portal` | +| Members and profiles | Not yet published | `area/members` | +| Design system and UI | Not yet published | `area/ui`, `design` | +| Nepali content and translation | Not yet published | `area/content`, `i18n`, `nepali-language` | +| Tooling and CI | Not yet published | `area/tooling`, `infra` | +| Accessibility | Not yet published | `a11y` | +| Security | Not yet published | See SECURITY.md — private reporting, never a public issue | diff --git a/PRIVACY.md b/PRIVACY.md new file mode 100644 index 0000000..2a640d6 --- /dev/null +++ b/PRIVACY.md @@ -0,0 +1,87 @@ +# Privacy Notice — devNepal + +> **Draft privacy notice for member accounts.** This notice describes the intended handling of personal information. + +**You can use devNepal, and contribute to it, without an account.** A profile is optional. If you create one it becomes public once approved, and your email address is never published. + +**Private contact:** not yet published. Do not submit personal information or account requests through public repository issues. + +--- + +## What we hold, and for how long + +### From GitHub, when you sign in + +| What | Why | Published | Kept | +|---|---|---|---| +| Username and account ID | Identifies your account and matches your work to your profile | **Yes** — username | Until you delete your profile | +| Profile picture | Shown on your profile. Loaded from GitHub; we keep no copy | **Yes** | — | +| Email address | To contact you about your account | **Never** | Removed within 30 days of deletion | + +We request access only to the account information needed for sign-in and account contact. We do not request access to your private repositories or permission to write to your GitHub account. + +### What you choose to add + +Display name · headline · organisation or university · location · short biography · up to five links to your own sites. These are the profile fields covered by this notice. + +All fields are optional individually, all are public once approved, and all are kept until you delete them. + +**A profile with nothing in it may not be approved**, because there is nothing for a reviewer to assess. You do not have to complete every field — only enough for us to see who you are. + +### Your public activity in our repositories + +We read public activity from our GitHub organisation — pull requests you opened or had merged, issues you opened or closed — and show it on your profile and on our home page. This information is already public on GitHub. + +**We do not read** your private repositories, your comments, or anything outside our own organisation. We cache it and refresh it periodically rather than calling GitHub on every visit. + +**We display no per-person contribution counts, scores or rankings.** The home page shows programme totals: merged pull requests, open issues and distinct contributors. + +Deleting your profile removes it from here. It remains on GitHub, which we do not control. + +### Automatically + +Standard server logs — network address, browser type, pages requested — kept 90 days for security and troubleshooting. **No advertising or tracking cookies.** + +--- + +## Your organisation and role are your own statement + +**Anything you enter about your employer, university or role is your own statement.** The site says so wherever it appears. + +Profiles are reviewed before they appear publicly. That review looks for impersonation and abuse, and **we may decline or remove a profile if we have reason to believe something in it is inaccurate.** + +**Approval is not verification.** We do not check every claim, we cannot, and the Government of Nepal does not vouch for what a member says about themselves. An approved profile means nothing obviously wrong was found — not that it was confirmed. + +Claiming an affiliation that is not yours breaches our Code of Conduct, and the profile will be removed. + +--- + +## Your profile is public once approved + +A new profile is **pending**: visible only to you, and returning "not found" on its public address. An administrator reviews it, usually within a day. + +Once approved it is publicly visible and may be indexed by search engines. Your email address is never part of that. + +**If you later change your headline or your organisation, the profile returns to pending** and is reviewed again. Those are the two fields the review exists to check. + +You can hide or delete your profile at any time from your profile settings. + +--- + +## Your rights + +**See** what we hold — most of it is on your profile page · **Correct** it, by editing your profile or contacting us · **Delete** it · **Object** to how we use it · **Complain** if you are unhappy with how we have handled it. + +Our response commitment for privacy requests is **within 15 working days**. + +We do not use your information for advertising or share it with advertisers. + +## Hosting and external services + +From initial deployment, devNepal's application, databases, runtime configuration, file storage, logs and backups will be hosted exclusively within Government of Nepal facilities. The same hosting requirement applies to applications developed through the devNepal programme. + +--- + +## Changes + +If we change this notice materially we will say so on the site rather than updating it quietly. diff --git a/README.md b/README.md index c399b00..eaa5afe 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,8 @@ scripts/setup.ts one-command local bootstrap compose.yaml PostgreSQL for development, plus api and migrate services .github/workflows/ci.yml Lint, typecheck, tests, build on every PR ``` +- **Project conventions.** Branch names, review policy, contribution guidance, + and documentation standards are in [docs/CONVENTIONS.md](./docs/CONVENTIONS.md). ## Working together (frontend + backend) diff --git a/README.ne.md b/README.ne.md new file mode 100644 index 0000000..65924a5 --- /dev/null +++ b/README.ne.md @@ -0,0 +1,98 @@ +# devNepal + +**सरकारी प्रविधि — सार्वजनिक रूपमा, सार्वजनिक योगदानसहित निर्मित।** + +प्रधानमन्त्री तथा मन्त्रिपरिषद्को कार्यालय, नेपाल सरकार + · [Read in English →](./README.md) + +> **हालको चरण: दस्तावेजीकरण र योजना।** + +--- + +## यो के हो + +devNepal मा नेपाल सरकारले प्रविधिसम्बन्धी परियोजनाहरू प्रकाशित गर्छ, र जो कोहीले तिनमा योगदान गर्न सक्छन्। सबै काम सार्वजनिक रिपोजिटरीमा हुन्छ। यो रिपोजिटरी devNepal का लागि हो। + +**devNepal ले बनाउँदै गरेको पहिलो परियोजना devNepal आफैँ हो — पहिलो कमिटदेखि नै सार्वजनिक रूपमा।** + +--- + +## यहाँबाट सुरु गर्नुहोस् + +| | | +|---|---| +| **[खुला इस्युहरू](../../issues)** | `ready` र `good-first-issue` दुवै लेबल भएका कामबाट सुरु गर्नुहोस् | +| **[CONTRIBUTING.md](./CONTRIBUTING.md)** | हामी कसरी काम गर्छौं, र कति समयमा जवाफ दिन्छौं | +| **[docs/CONVENTIONS.md](./docs/CONVENTIONS.md)** | ब्रान्चको नाम, कमिट सन्देश, लेबल, र काम पूरा भएको मानक | +| **[CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)** | आचरणसम्बन्धी अपेक्षा | +| **[SECURITY.md](./SECURITY.md)** | सुरक्षा समस्या निजी रूपमा जनाउनुहोस् — सार्वजनिक इस्युमा कहिल्यै नलेख्नुहोस् | +| **[GOVERNANCE.md](./GOVERNANCE.md)** | कसले के निर्णय गर्छ, र समीक्षा अधिकार कसले राख्छ | +| **[MAINTAINERS.md](./MAINTAINERS.md)** | कुन क्षेत्रमा कसलाई सोध्ने | +| **[PRIVACY.md — अङ्ग्रेजी मस्यौदा](./PRIVACY.md)** | सदस्य खाताका लागि गोपनीयता सूचनाको मस्यौदा | + +**योगदानका लागि devNepal खाता चाहिँदैन।** योगदान GitHub मा हुन्छ। devNepal प्रोफाइल ऐच्छिक हो। + +--- + +## योगदान कोडमा मात्र सीमित छैन + +डिजाइन, नेपाली अनुवाद, दस्तावेजीकरण, परीक्षण, पहुँचयोग्यता र सुरक्षासम्बन्धी कामको समान रूपमा समीक्षा गरिन्छ र श्रेय दिइन्छ। क्षेत्रगत सम्पर्कका लागि [MAINTAINERS.md](./MAINTAINERS.md) हेर्नुहोस्। यो सूचीमा नपरेको क्षेत्रमा योगदान गर्न चाहनुहुन्छ भने इस्यु खोलेर सोध्नुहोस्। + +--- + +## स्थानीय रूपमा काम गर्ने तरिका + +```bash +git clone https://github.com/SDOC-Team/devnepal.git +cd devnepal +``` + +पुल रिक्वेस्ट पठाउन [CONTRIBUTING.md](./CONTRIBUTING.md) हेर्नुहोस्। चलाउन मिल्ने एप्लिकेसन अझै छैन। + +--- + +## कहाँ के छ + +| पथ | हालको सामग्री | +|---|---| +| `docs/` | कार्यपरम्परा, उत्पादनका आवश्यकता र तयारीको प्रगति | +| `.github/` | इस्यु र पुल रिक्वेस्ट टेम्प्लेट | + +### योजनामा रहेको एप्लिकेसन संरचना + +| पथ | योजनामा रहेको सामग्री | +|---|---| +| `src/` | एप्लिकेसन | +| `ui/tokens/src/` | डिजाइन टोकन — रङ, स्पेसिङ, टाइप | +| `ui/css/` | स्टाइलसिट र साझा प्याटर्न | +| `locale/` | अङ्ग्रेजी र नेपालीका प्रयोगकर्ता-मुखी स्ट्रिङ | + +`ui/tokens/dist/` र `ui/css/dist/` स्रोतबाट पुनःनिर्माण गर्नुपर्छ र Git ले तिनलाई बेवास्ता गर्छ। + +--- + +## एप्लिकेसनका आवश्यकता + +- **अङ्ग्रेजी र नेपाली दुवैमा।** प्रकाशित प्रत्येक पृष्ठ दुवै भाषामा हुनुपर्छ। देवनागरीका लागि नेपालीको आफ्नै लाइन-हाइट चाहिन्छ +- **डिजाइन टोकन।** एप्लिकेसनको शैलीमा अर्थअनुसारका टोकन प्रयोग गर्नुपर्छ; रङ वा स्पेसिङका मान सिधै कोडमा नराख्नुहोस् +- **पहुँचयोग्यता।** किबोर्डबाट चल्ने, देखिने फोकस र नापिएको कन्ट्रास्ट v0.1 का आवश्यकता हुन्। पूर्ण पहुँचयोग्यता परीक्षण पछिको संस्करणका लागि स्थगित गरिएको छ +- **सबैका लागि उही जाँच।** समीक्षा आवश्यकता कोर टोली र बाह्य योगदानकर्ता दुवैलाई समान रूपमा लागू हुन्छ + +--- + +## के-के अहिले बनाइरहेका छैनौँ + +- सदस्य ब्लग र समुदाय-स्वामित्वका परियोजना सूची +- सार्वजनिक योगदान लिडरबोर्ड, क्रम वा अङ्क +- भत्ता वा बाउन्टी +- मन्त्रालयको आफ्नै प्रकाशन प्रणाली + +प्रत्येक कारणसहित स्थगित गरिएको हो, र आउँदा सूचनासहित आउनेछ। + +--- + +## अनुमतिपत्र र सञ्चालन + +[Apache License 2.0](./LICENSE)। जुनसुकै व्यक्ति वा कम्पनीले यो कोड प्रयोग, परिमार्जन र व्यावसायिक रूपमा उपयोग गर्न सक्छन्। **तपाईंको योगदानको प्रतिलिपि अधिकार तपाईंसँगै रहन्छ।** + +प्रधानमन्त्री तथा मन्त्रिपरिषद्को कार्यालयद्वारा सञ्चालित। मेन्टेनर सरकार बाहिरका पनि हुन सक्छन्। **मर्ज र डिप्लोयमेन्ट सरकारी टोलीले मात्र गर्छ।** diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..82a9dfc --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,49 @@ +# Security Policy + +## Reporting a vulnerability + +**Do not open a public issue.** + +### GitHub private vulnerability reporting + +If available, go to the **Security** tab of this repository → **Report a vulnerability** to submit a private report. + +Private reporting availability has not been verified, and no alternative private contact is published. If the reporting button is absent, do not post vulnerability details in an issue, pull request or branch. + +**Acknowledgement commitment: within 24 hours of receipt through the private reporting channel.** + +### What to include + +- What you found +- How to reproduce it +- What it affects, and what an attacker could do with it + +We will publish an advisory after remediation and credit you, unless you prefer otherwise. + +--- + +## Scope + +**In scope:** this repository, and the portal at once deployed. + +**Out of scope:** other government systems — each has its own disclosure path. Also out of scope: denial of service, social engineering, and automated scanner output without a demonstrated impact. + +--- + +## Safe harbour + +We will not pursue action against good-faith security research that: + +- Respects the privacy of others — do not access, modify or retain data belonging to another person +- Avoids degrading the service +- Gives us reasonable time to remediate before public disclosure + +If you are unsure whether something is in scope, ask first through the private reporting channel. + +--- + +## For contributors + +**Never commit a secret.** If you believe a credential has been exposed, report it privately and immediately — do not open an issue or a pull request describing it. + +If you find a security problem while working on an unrelated issue, stop and report it privately. A public fix is a public disclosure. diff --git a/docs/CONVENTIONS.md b/docs/CONVENTIONS.md new file mode 100644 index 0000000..3dd3fb5 --- /dev/null +++ b/docs/CONVENTIONS.md @@ -0,0 +1,138 @@ +# Conventions + +Reference material. [CONTRIBUTING.md](../CONTRIBUTING.md) explains how we work together; this is what to look up while doing it. + +--- + +## Branch names + +Format: `type/short-kebab-description`. Lowercase, hyphens, no issue numbers — the pull request links the issue, and a number in a branch name tells a reader nothing. + +| Prefix | Use when | Do not use when | +|---|---|---| +| `feat/` | The application can do something it could not before | You are correcting behaviour that was supposed to work — that is `fix` | +| `fix/` | Behaviour was wrong and is now correct | The behaviour was never specified. Adding it is `feat` | +| `docs/` | Only prose changes | Code changed too — use the code's prefix | +| `design/` | Visual or interaction change: tokens, patterns, layout, typography | It is purely accessibility — `a11y` is more specific and routes to a different reviewer | +| `a11y/` | Contrast, keyboard, focus, screen-reader behaviour, touch targets, semantic markup | — | +| `i18n/` | Translation, terminology, locale formatting, Devanagari rendering, `lang` attributes | You are changing the English wording itself — that is `docs` or `design` | +| `test/` | Adding or repairing tests, no production code touched | You fixed a bug and added a test proving it. That is `fix` — the test is part of the fix | +| `refactor/` | Structure changed, behaviour did not | Behaviour changed at all. Then it is `fix` or `feat` | +| `perf/` | Same behaviour, measurably faster or lighter | You have not measured it — that is `refactor` | +| `chore/` | Dependencies, CI config, tooling, lockfiles | It changes user-facing application behaviour — use `feat` or `fix` | + +**The rule that settles most disputes:** ask what a reader scanning history in a year would want to know. `refactor/` promises they can skip it. If something did change, you have misled them in a way that is expensive to discover. + +**When a change spans two types, split it.** If you cannot, use the prefix for the part carrying the most risk — a `fix` bundled with a `refactor` is a `fix`. + +When a change cannot be split, choose the first applicable type in this order: `fix`, `feat`, `a11y`, `i18n`, `design`, `perf`, `refactor`, `test`, `docs`, then `chore`. + +**Security fixes get no prefix of their own.** A public branch named for a vulnerability discloses it before the patch ships. See [SECURITY.md](../SECURITY.md). + +Contributors work on forks, so these names govern the core team and maintainers. Branch from `main`; there is no `develop`. Branches are deleted after merge. + +--- + +## Commit messages + +Conventional commits, with the same types as branch prefixes: + +``` +feat: add empty state to the members directory + +Explain why, if it is not obvious from the change. Wrap at 72 characters. + +Closes #42 +Signed-off-by: Your Name +``` + +- **Subject in the imperative** — "add", not "added" or "adds" +- **No full stop** at the end of the subject +- **Sign off every commit**: `git commit -s`. See the DCO section in CONTRIBUTING + +--- + +## Pull requests + +| | | +|---|---| +| **One issue per pull request** | If it grows, split it. We will ask, and explain why | +| **Title** | Same form as the commit subject | +| **Draft early** | Reviewing direction at 20% costs everyone less than at 100% | +| **Size** | Under ~400 changed lines where practical. Keep each PR focused on one coherent change; smaller PRs are generally easier to review thoroughly. | +| **Review** | A named maintainer (see ../MAINTAINERS.md) must review and approve the pull request before it can be merged | +| **Merge** | Use squash and merge by default; preserve a different strategy only when a maintainer documents why | +| **After merge** | Delete the working branch once the pull request is merged | + +--- + +## Issue Labels + +| Group | Labels | +|---|---| +| **Difficulty** | `good-first-issue` · `intermediate` · `advanced` | +| **Type** | `feature` · `bug` · `docs` · `design` · `a11y` · `i18n` · `test` · `infra` · `security` | +| **Area** | `area/portal` · `area/members` · `area/ui` · `area/content` · `area/tooling` | +| **Status** | `ready` · `needs-spec` · `blocked` · `claimed` · `stale` | +| **Meta** | `help-wanted` · `mentorship-available` · `nepali-language` | + +**Only claim issues labelled `ready`.** Anything labelled `needs-spec` is not yet settled enough to start, and working on it risks work we cannot accept. + +--- + +## What makes an issue ready + +If you are writing an issue, or wondering whether one is safe to start: + +- **Context** — why it exists and who it serves, assuming no prior knowledge +- **In scope** and **out of scope**, explicitly. The out-of-scope line is what protects your time +- **Acceptance criteria** — testable and enumerated +- **Where to look** — files, and an existing example to copy the pattern from +- **Tests expected** — automated tests or manual verification; explain when none apply +- **Size** — S (under 4h) · M (4–16h) · L (16–40h) +- **A named mentor** who will answer questions + +If an issue you want is missing any of these, say so in a comment. That is useful feedback, not a complaint. + +--- + +## What makes a pull request done + +- [ ] Acceptance criteria met +- [ ] Tests added or updated for behaviour changes +- [ ] Works in **both** English and Nepali +- [ ] Keyboard operable, focus visible, contrast sufficient +- [ ] Uses design tokens — **no raw colour or spacing values** +- [ ] No new dependency, or agreed in the issue first +- [ ] No secret and no real personal data anywhere in the diff +- [ ] Commits signed off + +--- + +## Code and interface conventions + +**Design tokens only.** Use `var(--dn-color-action)`, never `#C8102E`. Never reference a primitive such as `crimson-500` — application code uses semantic tokens. Raw colours belong only in `ui/tokens/src/`. + +**No user-facing text in components.** Every string goes in `locale/en.json` and `locale/ne.json` under the same key. Both files must contain the same keys. + +**Nepali is not a translation layer.** It has its own line-height token, because Devanagari matras need more vertical space than Latin. Do not unify them. Test with real Nepali strings, not placeholder text. + +**Dates in Bikram Sambat** wherever they are user-facing. + +**Never `outline: none`** without an equivalent visible replacement. + +--- + +## Adding a dependency + +Ask in the issue first, and say why nothing already present will do. This is a government supply chain, and every package is a long-term commitment someone will have to maintain. Most of the time the answer is to use what the framework already provides. + +Dependencies must use a licence approved for the project, have a clear source and maintainer, and have no known unresolved critical vulnerability. Do not add a dependency with unclear, proprietary, or otherwise unapproved terms. + +--- + +## Security + +**Never open a public issue, pull request or branch for a vulnerability.** Report privately — see [SECURITY.md](../SECURITY.md). + +If you find a security problem while working on something unrelated, stop and report it privately rather than fixing it in the open. A public fix is a public disclosure. diff --git a/docs/PRD-v0.1.md b/docs/PRD-v0.1.md new file mode 100644 index 0000000..47cac40 --- /dev/null +++ b/docs/PRD-v0.1.md @@ -0,0 +1,228 @@ +# devNepal Portal — Product Requirements, v0.1 + +**The full product scope is in [PRD.md](./PRD.md)** — this release covers roughly a fifth of it. Where the two disagree, this document governs. + +--- + +## 1. Purpose + +devNepal is where the Government of Nepal publishes technology work that anyone can help build. + +v0.1 establishes that it exists, that it is credible, and that contributing is genuinely possible. It does not onboard ministries or run the full contribution lifecycle. + +--- + +## 2. Users + +**Contributor** : someone whose work has been accepted on Github; no account needed on devNepal Portal. + +**Member** : someone who has a devNepal Portal account; no contribution needed on Github. + +| User | Needs from v0.1 | Not yet | +|---|---|---| +| **Contributor** | To find work matched to their skill and start without permission | — | +| **Member** | A public profile under their own name, showing their contributions once they exist | Scoring, badges, rankings | +| **Citizen or journalist** | To judge whether this is real and credible| Ministry-level browsing | + +A ministry official is not a v0.1 user. + +--- + +## 3. Scope + +### In + +Each row states what must be built, in enough detail to design and implement from. The `Traces to` column references requirements in the full PRD v0.9. A reduced or adapted reference does not imply that the entire original requirement is included; new v0.1 behaviour is labelled explicitly. + +| # | Capability | What it means | Traces to | +|:--|:-----------------|:--------------------------------------------------------------------|:--------| +| 1 | **Sign in with GitHub** | One button. A visitor authorises devNepal to read their public GitHub profile and nothing more, then returns to the site signed in. On first sign-in a profile record is created for them, holding their GitHub username, display name and avatar URL. No password is ever set, stored or reset — there is no email sign-up and no credentials form anywhere in the product | `AUTH-001` reduced; `AUTH-008` | +| 2 | **Member profile, self-edited** | A signed-in member can set a display name, a one-line headline, an organisation or university, a location, a short biography, and up to five links to their own sites. **Each field is optional and labelled as such.** A profile with nothing filled in may be declined, because a reviewer has nothing to assess — the interface should say so rather than letting someone submit an empty profile and wait. The biography is plain text, not formatted | `MEM-002` reduced; `MEM-003` adapted; `MEM-006`, `MEM-007`, `MEM-009` | +| 3 | **Approval before a profile is public** | A new or materially edited profile is *pending*: visible to its owner, invisible to everyone else, and returning 404 on its public URL. An administrator reviews it and approves or hides it. The member is told, on the edit page, that this is happening and roughly how long it takes. Review looks for impersonation and abuse, and may decline a profile where something appears inaccurate. **It is not a verification** — no claim is confirmed, and an approval means only that nothing obviously wrong was found | `ADM-002` reduced; new v0.1 profile approval rules | +| 4 | **Public member directory** | One page listing every approved profile as a card: avatar, display name, headline, organisation, location, and a link to that person's GitHub account. Newest approval first. A disclaimer stating that roles and organisations are self-declared is visible without scrolling. No email address appears, and no per-member counts of any kind | New v0.1 member-directory requirement | +| 5 | **Public member profile page** | One page per member at a stable URL based on their GitHub username, showing everything from row 2 plus their recent work if they have any. If they have none, that section is **absent rather than empty**, since most members will legitimately have none in the first weeks | `MEM-001`; `MEM-005` reduced; new v0.1 public-activity display | +| 6 | **Recent activity on the home page** | Above the fold: three counts describing the programme, and about ten recent events, each written as a readable sentence naming the person. | `GIT-007`, `GIT-008` adapted; new v0.1 programme totals | +| 7 | **Open issues on the contribute page** | A list of work currently available, read from GitHub, showing title, which repository, and its labels. Each links to the issue on GitHub, where claiming and contributing actually happen. A list, not a filterable browser | `DSC-001` adapted to GitHub issues | +| 8 | **Bilingual throughout** | Every page exists in Nepali and English at separate URLs, and **no page ships in only one language**. Nepali is not a translation layer added afterwards: it has its own line-height, because Devanagari needs more vertical space than Latin, and dates are shown in Bikram Sambat. Every string lives in a translation file rather than in the code | `NFR-I18N-01`; new v0.1 Bikram Sambat display rule | +| 9 | **Stable human-readable URLs** | Addresses are readable and permanent — `/en/members/username` rather than an opaque identifier. If a member changes their GitHub username, the old address keeps working by redirect. Retrofitting this later breaks every link already shared | `MEM-001`; `NFR-SEO-01`; new v0.1 username redirects | +| 10 | **Vulnerability disclosure path** | A published route for reporting a security problem privately, with a stated acknowledgement time of 24 hours. In v0.1 this is GitHub's private vulnerability reporting, because a dedicated address is not yet provisioned | `SEC-012` | +| 11 | **Repository ready for contribution** | The repository carries everything a stranger needs before contributing: licence, contribution guide, code of conduct, security policy, governance, named code owners, and issue and pull-request templates. Local setup works from a clean machine in under ten minutes | `BR-003` | +| 12 | **Server-rendered and search-visible** | Pages render on the server, so content is present without client-side JavaScript, is indexable, and loads quickly on a phone over a mobile connection. This is a baseline for a public government service, not an optimisation | `NFR-SEO-01`, `NFR-PERF-01` | +| 13 | **Administrative approval view** | A list of profiles, pending first, showing each member's claims alongside a link to their GitHub account that opens in a new tab, and the age of that account. Two actions: approve, hide. Each records who acted and when. The GitHub link is the whole control — it must be one click, or it gets skipped under volume | `ADM-002` reduced; `SEC-008` | + +Nothing in v0.1 is stubbed, faked or seeded with placeholder content. + +### Out + +| Deferred | Reason | +|---|---| +| Ministry publishing workflow (`GOV-*`) | Needs a named Product Owner per project | +| GitHub App, webhooks (`GIT-001`–`006`) | Public API read covers the display need | +| Recognition, badges, scoring (`REC-001`, `002`, `005`–`008`) | Needs verified contribution records | +| Leaderboards, rankings, per-person counts (`REC-003`) | Invites gaming; makes a legitimate zero look like a failing | +| Notifications (`NTF-*`) | Nothing to notify about | +| Moderation queues (`ADM-003`, `004`) | No user-generated content at this scale | +| Search and filtering (`DSC-002`) | Nothing to search at fifteen profiles | +| Member blogs (`BLG-*`), community projects (`PPR-*`) | Content-moderation surface disproportionate to the value | +| A dedicated activity page | The home-page strip carries the value while there is one repository. Returns when there are several | +| Activity charts, filters, graphs | GitHub Insights is free, public and better. Linked to instead | +| Contributor standing labels — maintainer, reviewer | Nobody is promoted in v0.1. Designed for, not populated | +| Separate project page | One project. Open issues live on the contribute page | +| Skills taxonomy, featured ordering, profile preview | Cosmetic | +| Stipends, bounties | Blocked on the procurement legal opinion | + +### 3.1 Activity — full definition + +**What an event is.** A pull request merged or opened, or an issue opened or closed, in any public repository of the organisation. Nothing else — in particular **not comments**, which are high in volume and low in signal. + +**How an event is displayed.** As a sentence a non-developer can read, with the date in Bikram Sambat and a link to the original on GitHub: + +> **12 Bhadra** — Sunita Rai improved the Nepali translation of the contribute page + +**On the home page:** three counts describing the programme — pull requests merged, open issues, and the number of distinct people who have contributed — then about ten events, newest first, and a prominent link to GitHub Insights for anyone wanting statistics. + +**On a member profile:** that member's own events, newest first, matched to their GitHub account rather than self-declared. The section is absent when there are none. + +**Freshness.** Data is refreshed on a schedule, not live. Every view states how old it is — *"as of 12 minutes ago"*. If a refresh fails, the previous data is shown with its age; **the page never goes blank**, because an empty credibility page is worse than a stale one. + +**Not shown:** comments, charts, graphs, filters, per-person counts, rankings, bot activity, or anything from a private repository. + +**Why the portal shows this at all**, given GitHub Insights exists and is better: aggregation across repositories, plain language for a non-developer, Nepali, and real names attached to GitHub usernames. + +### 3.2 What a public visitor's experience looks like + +A visitor arrives with one of two questions — *is this real?* or *can I help?* — and the site does not know which. Every page has to answer both without asking anything of them. + +1. Arrives on the home page, signed out. Nothing is asked of them: no account, no cookie banner, no interstitial +2. Understands within a minute what devNepal is, from the hero and three steps explaining how it works +3. **Above the fold, sees that work is actually happening** — three counts and about ten recent events, each naming a real person and linking out to GitHub. This is what answers *is this real?*, and it is checkable in one click without a GitHub account or knowing what a pull request is +4. Can follow any event to the original on GitHub, and read the actual change and discussion +5. Goes to the members directory to see who is behind it. Each profile links to that person's GitHub account, so every claim is independently verifiable — the site does not ask to be trusted +6. Goes to the contribute page to find work. Open issues are listed with their labels; each links to GitHub, where claiming and contributing happen +7. Reads *what we are not building yet* on the home page, and learns what is deliberately absent rather than wondering what is missing +8. Contributes — **without ever creating an account here.** A profile is something they may want afterwards, never a gate before. From here the sequence continues in the contributor's section below. + +**Every page works signed out**, and no page withholds content behind a sign-in. The only signed-in surfaces are editing your own profile and the administrative approval view. + +If a visitor follows a stale or shared link to a profile that is pending or hidden, they see *not found* — never an error page and never a confirmation that the profile exists. + +The thing most often built badly here is step 3. A home page that describes intentions rather than showing evidence leaves a sceptical reader with nothing to check, and that reader is the one who decides whether the launch is credible. + +### 3.3 What a contributor's experience looks like + +**Six of the nine steps happen on GitHub, not here.** That is the honest shape of the product: the portal's job is to help someone find work and to collect the credit afterwards. The work itself, and every review, happens where the code is. + +1. **Finds an issue** — from the contribute page here, or directly on GitHub +2. **Reads it and can start without asking a question.** Context, what is in and out of scope, testable acceptance criteria, where to look, and a named mentor. An issue missing any of these is not ready to be claimed +3. **Claims it by commenting.** A maintainer assigns it. If there is no activity for 14 days a bot unassigns it, so issues do not sit idle — this is never a judgement, and it can be claimed again +4. **Works on their own fork**, branches from `main`, and opens a pull request with every commit signed off +5. **Gets a human response within three days**, and is told which review lane the change falls into — so they know whether to expect a merge this week or after the weekend session +6. **Iterates if asked.** A maintainer approves; the government team merges +7. **Is credited in the repository history**, whether or not they ever create a profile here +8. **Optionally creates a profile**, at which point their merged work appears on it automatically — they do nothing to make that happen +9. **Comes back, or does not.** What decides it is almost never the difficulty of the work + +**Step 2 is where contribution is won or lost.** A contributor who has to ask three questions before starting usually does not start, and the out-of-scope line is what protects their weekend from a change we would decline. + +**Step 5 is where they are lost.** Silence is worse than a slow merge, and a decline without an explanation of what would have been accepted is worse than both. Whatever else slips, the three-day response does not. + +**Non-code contributors follow the same path.** A translation review, an accessibility audit or a documentation fix is claimed, reviewed and credited identically. Nothing about this sequence assumes the contribution is code. + +### 3.4 What a member's experience looks like + +A designer and developer need this as a sequence, not a feature list. + +1. Arrives at the sign-in page. One button, one line naming the permission requested +2. Authorises on GitHub, returns signed in +3. Lands on their own profile edit page, with a banner explaining that the profile is pending review and will be public once approved +4. Fills in the fields they choose. Saves. The banner persists. An entirely empty profile is not submittable +5. An administrator approves. The profile becomes public and appears in the directory +6. Later, once they have contributed, their work appears on the profile automatically — they do nothing to make that happen +7. At any point they can change their details, hide their profile, or delete it. Editing the headline or organisation returns it to pending, and they are told so + +Step 3 is the one most often built badly: without that banner a member fills in a profile, sees nothing public, and concludes the site is broken. + +--- + +## 4. Success criteria + +Measured at the launch gate. + +| Measure | Target | +|---|---| +| Approved member profiles | ≥ 15. Below this the directory reads as abandoned rather than new | +| Merged pull requests from outside the core team | ≥ 8 | +| Members whose profile shows a contribution | ≥ 3 | +| Every contribution acknowledged | Within 3 days of being opened, without exception. Acknowledgement means a human reply, not a label | +| Bilingual completeness | 100% of shipped pages | +| Structural accessibility | Every item met on every shipped page | +| Open security findings | 0 | +| Clone to running locally | Under 10 minutes on a machine that has never seen the project, following only the written instructions | +| Activity record freshness | Under 30 minutes behind GitHub, with the age always displayed | + +Not measured: page views, sign-ups, stars, lines of code. + +**If the first four are not met, the launch is delayed.** + +### 4.1 Accessibility + +**Required in v0.1.** Each is cheap now and expensive to retrofit, because it is structural rather than cosmetic. + +| Requirement | What it means in practice | +|---|---| +| Semantic HTML | Real headings in order, landmarks, lists, and native buttons and links rather than styled `div`s. This is what assistive technology navigates by | +| Keyboard operability | Every action reachable and completable without a mouse, in a sensible order, with no element that traps focus | +| Visible focus | A clearly visible indicator on whatever is focused, meeting 3:1 contrast against its surroundings. Nothing removes the outline without replacing it | +| Contrast, measured | Every text-on-background pair checked with a tool, not judged by eye, in light and dark | +| Correct `lang` | Set on the page, and on any element whose language differs from it. Without it a screen reader reads Devanagari as English | +| Alternative text | On every image, including avatars | + +**Deferred to a later release, and stated publicly as deferred.** Additive work that does not change the structure: + +full WCAG 2.2 AA audit and conformance statement · manual screen-reader pass · reduced-motion handling · AA coverage across every component state. + +**No conformance claim is made until it has been tested.** Fixing contrast is a one-line change at any point; retrofitting semantic markup across a built site is a rewrite. + +--- + +## 5. Principal risk + +The directory publishes **self-declared affiliations on a `gov.np` domain**. A false claim would make the government the publisher of a false statement about a named person and a named organisation. + +Three controls, all mandatory: +1. **Approval before display.** A profile is `pending` until an administrator approves it, and returns 404 publicly until then. Review looks for impersonation and abuse, and may decline a profile where something appears inaccurate. **Approval is not verification** — no claim is confirmed, and nothing about an approved profile is warranted by the government +2. **Self-declared labelling.** Wherever an organisation or role appears — card, profile, administrative view — a visible line states that it is provided by the member and not verified by the Government of Nepal. On the directory it is visible without scrolling +3. **No email, no organisational voice.** Email addresses never appear in any page or response. A profile may describe an individual's role; it may not be written as though the organisation itself is speaking + +The link to a member's GitHub account is the trust mechanism, because it lets any reader verify independently. It is prominent on the card, the profile, and the administrator's approval view. + +--- + +## 6. Constraints + +| | | +|---|---| +| Personal data | Only GitHub identity and what a member volunteers. Email is stored for account contact and **never** appears in any page, response or log | +| No file uploads | Avatars are loaded from GitHub by URL. Nothing is uploaded to us, which removes file storage, malware scanning and content-type validation from this release entirely | +| One server-side credential | Reading public GitHub data at a usable rate needs a token. It is server-side, holds no permissions, and can read nothing a signed-out visitor could not already see | +| Bilingual is a gate | A page does not ship in one language. This constrains scope: every capability costs its Nepali translation and a native-speaker review | +| Stack | Chosen for depth of the local hiring pool, which outranks the team's own preference. The government must be able to hire maintainers in Kathmandu in three years | + +--- + +## 7. What unblocks each deferred capability + +For the deferrals, what has to be true before they can be taken up. + +| Deferred capability | Unblocked by | +|---|---| +| Ministry publishing workflow | A named Product Owner in a department, with allocated hours | +| Verified contributions, recognition, badges | Independent security review of the identity layer | +| Notifications | Something worth notifying a member about — in practice, recognition or ministry projects | +| Moderation queues | User-generated content, which arrives with blogs or community projects | +| Search and filtering | Roughly fifty profiles | +| A dedicated activity page | Several repositories worth aggregating | +| Contributor standing labels | The first promotions | +| Stipends, bounties | The procurement legal opinion | + +--- diff --git a/docs/PRD.md b/docs/PRD.md new file mode 100644 index 0000000..8784cd4 --- /dev/null +++ b/docs/PRD.md @@ -0,0 +1,847 @@ +**GOVERNMENT OF NEPAL** + +**Office of the Prime Minister and Council of Ministers** + +Digital Collaboration Initiative + +**DevNepal** + +**Software Requirements Specification and Project Scope** + +> **Document purpose:** Define the product scope, operating model, functional and non-functional requirements, governance controls, delivery phases, and acceptance basis for a national platform that enables volunteers to contribute to government technology projects and strengthens Nepal's developer community. + +Document metadata + +| Field | Value | +|------------------|------------------------------------------------------------------------------------------------------------------------------------------------| +| Document status | Draft for stakeholder validation | +| Version | 0.9 | +| Date | 2 September 2026 | +| Prepared for | Office of the Prime Minister and Council of Ministers, Government of Nepal | +| Primary audience | PMO leadership, participating ministries, product team, engineering team, security reviewers, legal/policy reviewers, and community moderators | + +*This is a requirements and planning draft. It does not by itself approve policy, procurement, data processing, hosting, open-source licensing, or public release of any government system.* + +> ### Reading this alongside the current release +> +> **This document is the full product scope.** It describes devNepal as intended when complete, and was written before the first release was built. +> +> **What the current release builds is in [PRD-v0.1.md](./PRD-v0.1.md)**, which covers roughly a fifth of the requirements below. Where the two disagree, the current release governs. +> +> Requirement IDs here (`AUTH-001`, `GOV-004`, and so on) are the stable references. The current release traces back to them. + +--- + + +# Contents +- 1\. Executive Summary + +- 2\. Background, Vision and Principles + +- 3\. Objectives and Success Measures + +- 4\. Stakeholders, Users and Authorization + +- 5\. Project Scope + +- 6\. Operating Model and Core Workflows + +- 7\. Functional Requirements + +- 8\. Business Rules + +- 9\. Information and Data Requirements + +- 10\. Integration Requirements + +- 11\. Non-Functional Requirements + +- 12\. Security, Privacy and Legal Requirements + +- 13\. Community and Content Governance + +- 14\. User Experience, Accessibility and Localization + +- 15\. Delivery Scope and Phasing + +- 16\. Acceptance and Readiness + +- 17\. Risks and Mitigations + +- 18\. Assumptions, Dependencies and Decisions Required + +- Appendices + +# 1. Executive Summary +DevNepal is proposed as the Government of Nepal's public collaboration and developer-community platform. Participating ministries will publish suitable technology projects that need public contribution; members will discover opportunities, contribute through approved workflows, build a public portfolio, publish technical writing, and receive verified recognition for accepted work. The platform will also allow members to list their own public projects and external work links. + +DevNepal should be treated as a trusted registry and collaboration layer, not as a replacement for GitHub. Source code, branches, issues, pull requests, continuous integration, and code review remain in approved repositories. DevNepal provides identity, project discovery, structured project metadata, applications and participation records, verified contribution events, community content, recognition, governance, and reporting. + +> **Key product recommendation:** Measure and recognize accepted impact in DevNepal-listed projects, not raw commit volume. GitHub profile activity may be displayed with consent, but official leaderboards should rely on verified events such as merged pull requests, accepted documentation/design/QA work, completed issues, and maintainer-approved non-code contributions. + +The platform must implement three authorization roles requested by PMO: Super Admin, Ministry Publisher, and Member. Public visitors are an unauthenticated access state, not an administrative role. For security and accountability, a ministry must be represented by an organization record with named officer accounts; shared ministry credentials are not acceptable. + +# 2. Background, Vision and Principles +## 2.1 Background +Government technology projects often need specialized, time-bound contributions in software engineering, user experience, documentation, quality assurance, cybersecurity, data, localization, and research. At the same time, many Nepali developers want credible ways to contribute to public-interest technology, find peers, demonstrate skills, and learn from real projects. DevNepal connects these needs through a governed, transparent platform. + +Comparable public-code initiatives emphasize discoverable inventories, consistent metadata, reusable software, and clear contribution channels. The U.S. Federal Source Code Policy highlights inventories, reuse, public access, and reduced duplication, while the Standard for Public Code emphasizes visible contact channels and contribution guidance \[R1, R2\]. DevNepal adapts those principles to Nepal's institutional and legal context rather than copying another country's policy. + +## 2.2 Vision +> **Vision:** Create Nepal's trusted public-interest developer network where government institutions can safely open appropriate projects to contribution, and where developers can build capability, reputation, and community by delivering visible public value. + +## 2.3 Guiding principles +- Public value first: every government listing states the citizen or institutional outcome, not only the technology task. + +- Open by suitability, not by default: only projects cleared for public participation are listed; classified, sensitive, procurement-restricted, or personally identifiable data is excluded. + +- Contribution must be easy: every project exposes a maintained contact, contribution guide, suitable starter work, response expectations, and decision process. + +- Trust through verification: official projects, ministry identities, contribution records, and recognition are verifiable and auditable. + +- Privacy by design: collect the minimum data needed, make public visibility explicit, and allow account disconnection and deletion subject to lawful retention. + +- Security throughout delivery: apply secure-development practices to DevNepal and require baseline repository hygiene for listed government projects \[R10, R11\]. + +- Inclusive by design: English and Nepali support, mobile responsiveness, low-bandwidth behavior, and WCAG 2.2 Level AA are baseline requirements \[R9\]. + +- Technology neutrality: requirements define outcomes and controls; implementation choices remain replaceable and maintainable. + +# 3. Objectives and Success Measures +## 3.1 Business objectives +- Enable authorized ministries to publish structured, approved project opportunities requiring public contribution. + +- Reduce friction between an interested volunteer and a first meaningful contribution. + +- Build a searchable national directory of developers, skills, public projects, technical writing, and verified contribution experience. + +- Improve transparency around the status, maintainers, needs, and outcomes of suitable government technology projects. + +- Strengthen open, secure, reusable government software practices and reduce duplicated effort where policy permits. + +- Give PMO and ministries measurable insight into participation, responsiveness, contribution outcomes, and project health. + +## 3.2 Outcome metrics +Proposed measurement framework; numeric targets to be approved after pilot baselining + +| Outcome | Metric definition | Review cadence | +|------------------------|------------------------------------------------------------------------------------------------------------------------------------|--------------------| +| Institutional adoption | Number of ministries with an active named publisher and at least one approved public project. | Monthly | +| Opportunity supply | Active projects by ministry, contribution type, difficulty, and expected effort. | Monthly | +| Contributor activation | Percentage of new members who save, apply to, or contribute to a project within 30 days. | Monthly | +| First-response quality | Median time from a member question/application/pull request to a meaningful maintainer response. | Weekly | +| Verified impact | Accepted contribution records, unique contributors, completed milestones, and completed projects. | Monthly | +| Inclusion | Participation by province, skill area, language preference, and experience band, reported only at privacy-safe aggregation levels. | Quarterly | +| Community health | Retention, repeat contributors, reports, moderation turnaround, and code-of-conduct incidents. | Monthly | +| Platform reliability | Availability, performance, sync freshness, security findings, and support resolution. | Monthly | + +# 4. Stakeholders, Users and Authorization +## 4.1 Stakeholders +Stakeholder responsibilities + +| Stakeholder | Primary interest / responsibility | +|---------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------| +| PMO sponsor and steering committee | Own mandate, policy decisions, inter-ministry participation, funding, risk acceptance, and final scope approval. | +| DevNepal product owner | Own roadmap, requirements, backlog, outcomes, release decisions, and cross-functional coordination. | +| Super Admin team | Provision ministries and named publishers, approve listings, manage taxonomy, moderate content, audit actions, and operate the platform. | +| Ministry project owner / publisher | Publish accurate project information, maintain contribution channels, respond to contributors, verify accepted work, and close/archive projects. | +| Members / volunteers | Maintain truthful profiles, follow project rules and code of conduct, contribute through approved channels, and report abuse/security concerns. | +| Repository maintainers | Triage issues, review contributions, protect branches, run tests, manage releases, and send authoritative contribution events. | +| Security, privacy and legal reviewers | Approve controls, data handling, terms, licenses, incident processes, and public-release boundaries. | +| Public visitors | Browse public projects, member profiles where permitted, blogs, results, and public reports. | + +## 4.2 Authorization model +Role and permission summary + +| Capability | Super Admin | Ministry Publisher | Member | Public visitor | +|--------------------------------------|---------------------|--------------------------------------------------|----------------------------|------------------------| +| Manage ministry organizations | Create / suspend | View own | No | No | +| Manage named ministry officers | Create / revoke | No by default | No | No | +| Create government project | Any ministry | Own ministry | No | No | +| Approve government project | Yes | Submit only | No | No | +| Edit published government project | Any | Own ministry; material edits may re-enter review | No | No | +| Create personal project | Yes | If also a member profile | Own | No | +| Contribute / apply | If member-enabled | If member-enabled | Yes | No | +| Publish technical blog | Yes | If member-enabled | Own; subject to moderation | No | +| Verify contribution | Override with audit | Own ministry projects | Submit evidence only | No | +| Moderate / suspend | Yes | Report only | Report only | No | +| View audit and operational analytics | All | Own ministry | Own activity | Public aggregates only | + +> **Control requirement:** A ministry organization may have one or more named publisher accounts, but credentials must never be shared. Each publish, approval, verification, suspension, and material edit must be attributable to a named person in an audit log. + +# 5. Project Scope +## 5.1 In scope +- Public web application for desktop, tablet, and mobile browsers. + +- Public catalog of approved government contribution projects and member-owned public projects. + +- Member registration, profile, skills, education, links, portfolio, availability, and privacy controls. + +- Super Admin provisioning of ministries and named ministry publishers. + +- Government project drafting, approval, publication, maintenance, contribution intake, completion, and archival. + +- Project search, filters, recommendations based on explicit skills/interests, bookmarks, and application/interest workflows. + +- GitHub account connection and permissioned synchronization of profile/activity data. + +- GitHub App integration for verified events from selected DevNepal-listed repositories. + +- Member technical blogs in a safe Markdown-based editor and external links to Medium or other publications. + +- Recognition profiles, badges, and a quality-based leaderboard using verified accepted contributions. + +- In-app and email notifications for material workflow events. + +- Moderation, reports, taxonomy, analytics, audit trails, consent, retention, and account lifecycle controls. + +- English and Nepali interface and content metadata, Unicode search, accessibility, and low-bandwidth behavior. + +## 5.2 Explicitly out of scope +- Hosting source code, branches, issues, pull requests, CI/CD pipelines, packages, or releases inside DevNepal. + +- Publishing classified, security-sensitive, procurement-confidential, law-enforcement-sensitive, or personal-data-bearing government projects for open contribution. + +- Production deployment privileges for volunteers or automatic merging of contributor code. + +- Government procurement, tendering, employment, payroll, grants, bounties, or contract management. + +- A general social network with private messaging, follower feeds, live chat, or unrelated user-generated content. + +- Mirroring a member's complete Git history or importing private repository details without explicit repository-level authorization. + +- Automatic legal approval of licenses, contributor agreements, data release, or source-code publication. + +- Native mobile applications in the initial delivery. + +- AI-generated project scoring or automated contributor selection in the MVP. + +## 5.3 Scope boundary: public contribution suitability +Before a government project enters DevNepal, its ministry owner must complete a suitability checklist covering legal authority, source-code rights, data classification, security exposure, procurement restrictions, third-party licenses, repository readiness, maintainer capacity, contribution agreement, and public communications. Super Admin approval confirms completion of the process, not a transfer of legal responsibility from the ministry. + +# 6. Operating Model and Core Workflows +## 6.1 Government project lifecycle +Lifecycle states and controls + +| State | Meaning | Allowed transition / control | +|-----------------------|---------------------------------------------------------------------------------------------|--------------------------------------------------------| +| Draft | Visible only to the owning ministry and Super Admin. | Ministry edits; submit for review. | +| In review | PMO review of completeness, suitability, licensing, security classification, and readiness. | Approve, request changes, or reject. | +| Changes requested | Returned with actionable review comments. | Ministry edits and resubmits. | +| Approved / scheduled | Approved but not yet public, optionally with a future publication date. | Super Admin publishes or revokes approval. | +| Open for contribution | Public, accepting volunteers or contribution events. | Pause, mark in progress, complete, cancel, or archive. | +| Paused | Public status visible; new applications disabled while existing work is retained. | Resume, complete, cancel, or archive. | +| Completed | Outcome and release/results summary published; no new work accepted. | Archive after retention period or reopen by approval. | +| Cancelled | Reason published unless restricted; no new work accepted. | Archive or reopen by approval. | +| Archived | Read-only historical record retained according to policy. | Super Admin restore only. | + +## 6.2 End-to-end contribution workflow +1. A ministry prepares the project, identifies maintainers, selects an approved repository and license, defines contribution types and tasks, and submits the listing. + +2. Super Admin verifies suitability and completeness, records review comments, and approves publication. + +3. A member discovers the project, reviews prerequisites and contribution instructions, connects GitHub if needed, and expresses interest or starts a labeled task. + +4. The ministry/maintainer acknowledges participation, assigns or confirms work where assignment is required, and communicates through the public repository or approved channel. + +5. The member contributes through GitHub or submits evidence for approved non-code work such as UX, documentation, translation, testing, or research. + +6. GitHub webhooks or the ministry reviewer create a candidate contribution record. The maintainer accepts, rejects, or requests clarification with a reason. + +7. Accepted work updates the member's verified portfolio and project metrics. Recognition/leaderboard changes remain auditable and reversible. + +8. The ministry publishes progress and completion outcomes, credits contributors, and archives the listing when appropriate. + +## 6.3 Personal project workflow +Members may list projects they own or maintain, with GitHub, demo, Medium, website, documentation, or other approved URLs. Personal projects are clearly distinguished from official government projects. Ownership may be verified through the connected GitHub account, domain verification, or manual moderation. Misleading government branding, unsafe links, copied content, or unlawful material is prohibited. + +# 7. Functional Requirements +Priority uses MoSCoW: Must = required for production launch; Should = important for the first public release but may be deferred with approved risk; Could = later enhancement; Won't = excluded from the current scope. + +Table 7A. Identity, authentication and authorization requirements + +| ID | Requirement | Priority | +|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| +| AUTH-001 | The platform shall provide federated sign-in for members using approved providers, including Google, GitHub, and Facebook when enabled by configuration and policy. | Must | +| AUTH-002 | The platform shall allow a member to connect or disconnect GitHub independently of the provider used to sign in. | Must | +| AUTH-003 | The platform shall provision the first Super Admin through a controlled deployment process and require all subsequent Super Admin grants to be auditable. | Must | +| AUTH-004 | Only a Super Admin shall create, activate, suspend, or revoke a ministry organization and its named publisher accounts. | Must | +| AUTH-005 | Super Admin and Ministry Publisher accounts shall use multi-factor authentication and verified official contact information. | Must | +| AUTH-006 | Authorization shall be enforced server-side for every protected object and action, including ownership and ministry boundaries. | Must | +| AUTH-007 | The platform shall provide secure session revocation, device/session listing for privileged users, inactivity timeout, and re-authentication for high-risk actions. | Must | +| AUTH-008 | The platform shall record provider consent, scopes, connection time, last synchronization, and revocation status without exposing tokens to users or logs. | Must | +| AUTH-009 | A suspended account shall lose authenticated access immediately while public records follow moderation and retention policy. | Must | +| AUTH-010 | Members shall be able to export their profile and contribution records and request account deletion, subject to lawful and audit retention. | Should | + +Table 7B. Member profile requirements + +| ID | Requirement | Priority | +|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| +| MEM-001 | A member shall have a unique public username and immutable internal identifier. | Must | +| MEM-002 | A member profile shall support name, photograph, headline, biography, location, preferred language, skills, education, experience band, availability, interests, and contribution preferences. | Must | +| MEM-003 | A member shall control visibility of optional fields; email, authentication provider, and private contact information shall be non-public by default. | Must | +| MEM-004 | Skills shall be selected from an admin-managed taxonomy with optional suggestions for missing terms. | Must | +| MEM-005 | A profile shall display government and personal projects, technical blogs, verified contributions, badges, and connected external links in separate sections. | Must | +| MEM-006 | A member shall be able to link GitHub, Medium, personal website, portfolio, and other allowlisted URL types. | Must | +| MEM-007 | External URLs shall be validated, normalized, checked against unsafe schemes, and rendered with clear external-link labeling. | Must | +| MEM-008 | A member shall be able to preview the public profile before publishing changes. | Should | +| MEM-009 | The platform shall support profile completeness guidance without making sensitive optional data mandatory. | Should | +| MEM-010 | Members shall be able to report impersonation and request verification of a disputed identity or project ownership claim. | Must | + +Table 7C. Government project publishing requirements + +| ID | Requirement | Priority | +|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| +| GOV-001 | A Ministry Publisher shall create and edit project drafts only for the ministry organizations to which the account is assigned. | Must | +| GOV-002 | A government project shall capture structured fields defined in Appendix A, including outcome, requirements, contribution types, maintainer, repository, license, data classification, milestones, and response expectations. | Must | +| GOV-003 | A government project shall support proposal, requirements, architecture, design, and other approved attachments with version, file type, size, and malware controls. | Must | +| GOV-004 | The platform shall support save-as-draft, preview, submit, change-request, approve, schedule, publish, pause, complete, cancel, archive, and restore actions according to the lifecycle. | Must | +| GOV-005 | Every review action shall record actor, timestamp, decision, reason/comment, and before/after version. | Must | +| GOV-006 | A material edit to license, repository, data classification, scope, contribution agreement, or public-contact information shall return a published project to review or require Super Admin approval. | Must | +| GOV-007 | Each open project shall expose contribution instructions, communication channel, expected first-response time, difficulty, effort, prerequisites, and at least one actionable task or workstream. | Must | +| GOV-008 | A project shall support code and non-code contribution categories including engineering, UI/UX, QA, security, data, documentation, localization, research, and community support. | Must | +| GOV-009 | A Ministry Publisher shall post progress updates, milestone status, release/result links, completion summary, and contributor acknowledgements. | Should | +| GOV-010 | Expired deadlines shall not silently close a project; the owner shall explicitly extend, pause, complete, cancel, or archive it. | Must | +| GOV-011 | The platform shall display an official-government badge only on Super Admin-approved ministry projects. | Must | +| GOV-012 | A project with no maintainer response within the configured SLA shall be flagged to the ministry and Super Admin. | Should | + +Table 7D. Member-owned project requirements + +| ID | Requirement | Priority | +|---------|----------------------------------------------------------------------------------------------------------------------------------------------------|--------------| +| PPR-001 | Members shall create, edit, unpublish, and archive their own personal project listings. | Must | +| PPR-002 | Personal projects shall support title, summary, description, role, status, technology, skills, dates, images, and external URLs. | Must | +| PPR-003 | The interface shall clearly label personal projects as community projects and never imply Government of Nepal endorsement. | Must | +| PPR-004 | The platform shall attempt ownership verification for connected GitHub repositories and record verified/unverified status. | Should | +| PPR-005 | Personal projects shall be subject to automated link/file checks, community reports, and Super Admin moderation. | Must | +| PPR-006 | A member may invite collaboration on a personal project only after accepting the community terms and publishing contribution/contact instructions. | Could | + +Table 7E. Discovery, application and participation requirements + +| ID | Requirement | Priority | +|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| +| DSC-001 | Public users shall browse approved projects without signing in. | Must | +| DSC-002 | Search shall support title, summary, ministry, technology, skill, contribution type, status, difficulty, effort, deadline, and language filters. | Must | +| DSC-003 | Search and URLs shall support Nepali Unicode and stable, human-readable project slugs. | Must | +| DSC-004 | Members shall bookmark projects and receive opt-in change notifications. | Should | +| DSC-005 | Members shall express interest, apply to a controlled workstream, or follow direct-contribution instructions according to the project mode. | Must | +| DSC-006 | Application forms shall capture only project-relevant information and support screening questions configured by the ministry. | Must | +| DSC-007 | Ministry Publishers shall accept, waitlist, decline, or request information from applicants with auditable status and reusable response templates. | Should | +| DSC-008 | The platform shall preserve an application/activity timeline visible to the member and authorized ministry users. | Must | +| DSC-009 | Public project pages shall show maintainer activity indicators and stale-project warnings without exposing private operational data. | Should | +| DSC-010 | Recommendations shall be explainable and initially based on explicit profile skills, interests, language, effort, and project needs rather than opaque AI scoring. | Should | + +Table 7F. GitHub integration requirements + +| ID | Requirement | Priority | +|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| +| GIT-001 | The platform shall use a registered GitHub App for repository-level integration and user authorization, using the minimum permissions required \[R3\]. | Must | +| GIT-002 | Connecting GitHub shall import only consented profile fields and public activity needed for the selected DevNepal features. | Must | +| GIT-003 | The platform shall allow a user or repository owner to select which repositories the GitHub App may access. | Must | +| GIT-004 | The platform shall subscribe to webhooks rather than relying only on polling and shall validate every webhook signature using a high-entropy secret \[R4\]. | Must | +| GIT-005 | Webhook processing shall be idempotent, queued, retryable, timestamped, and protected against replay and duplicate delivery. | Must | +| GIT-006 | The platform shall reconcile selected repositories periodically to recover missed webhook events while respecting GitHub rate limits. | Must | +| GIT-007 | Verified project activity shall include configured events such as pull-request merged, issue closed, approved review, release, and qualifying commits to the default branch. | Must | +| GIT-008 | Raw commits, merge commits, automated/bot events, and duplicated events shall not directly generate leaderboard credit. | Must | +| GIT-009 | A member may display an annual GitHub contribution calendar or summary where supported, with source and freshness labels; it shall not be presented as an exact all-time work record \[R5\]. | Should | +| GIT-010 | Private repository names, code, issue content, commit messages, or URLs shall never be public; private activity counts shall be omitted unless explicitly authorized and policy-approved. | Must | +| GIT-011 | On GitHub authorization revocation or app uninstall, synchronization shall stop, tokens shall be invalidated/deleted, and the profile shall show a disconnected state. | Must | +| GIT-012 | Each imported event shall retain provider event ID, repository ID, actor mapping, received time, processing state, and verification provenance for audit and deduplication. | Must | + +Table 7G. Technical blog requirements + +| ID | Requirement | Priority | +|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| +| BLG-001 | Members shall create, preview, save, publish, edit, unpublish, and archive technical blog posts. | Must | +| BLG-002 | The editor shall support safe Markdown, code blocks, images, links, headings, tables, and accessible alternative text. | Must | +| BLG-003 | Rendered content shall sanitize HTML, prohibit executable scripts/iframes by default, and protect against stored cross-site scripting. | Must | +| BLG-004 | Posts shall support title, excerpt, cover image, tags, language, reading time, publication date, and canonical external URL. | Must | +| BLG-005 | Members may list an external Medium or other article as a link without copying the full text; import requires rights confirmation and supported API/format. | Should | +| BLG-006 | Posts shall support moderation states and community reporting while preserving version/audit history for moderators. | Must | +| BLG-007 | Government or project-official posts shall require an explicit official publishing permission and visual label distinct from personal member writing. | Must | + +Table 7H. Recognition and leaderboard requirements + +| ID | Requirement | Priority | +|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| +| REC-001 | Recognition shall be based on verified accepted contribution records, not total commits or self-reported activity. | Must | +| REC-002 | The scoring policy shall be publicly documented, configurable, versioned, and approved by the product owner before activation. | Must | +| REC-003 | The platform shall support rolling-period, annual, ministry, project, contribution-type, and lifetime views without exposing private data. | Should | +| REC-004 | Members shall be able to opt out of public leaderboard display while retaining private contribution history. | Must | +| REC-005 | Moderators shall reverse, correct, or invalidate recognition with a reason and audit record. | Must | +| REC-006 | Rate caps, bot exclusion, duplicate detection, maintainer separation-of-duties, and anomaly review shall reduce gaming. | Must | +| REC-007 | Badges shall have documented criteria, evidence, issuer, issue date, and revocation state. | Should | +| REC-008 | The platform shall recognize approved non-code contributions so that design, QA, documentation, translation, security, and research are not disadvantaged. | Must | + +Table 7I. Notification requirements + +| ID | Requirement | Priority | +|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| +| NTF-001 | The platform shall provide in-app notifications for approvals, review comments, applications, assignments, contribution verification, moderation, and security events. | Must | +| NTF-002 | Users shall control non-essential email categories and digest frequency; mandatory security/administrative notices cannot be disabled. | Must | +| NTF-003 | Notification messages shall avoid sensitive content in email subject lines and shall link to authenticated detail when needed. | Must | +| NTF-004 | Delivery failures shall be logged and retried without duplicate user-visible notifications. | Should | + +Table 7J. Administration and moderation requirements + +| ID | Requirement | Priority | +|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| +| ADM-001 | Super Admin shall manage ministries, named publisher accounts, skills/tags, project categories, approved licenses, contribution types, badges, moderation reasons, and feature flags. | Must | +| ADM-002 | Super Admin shall review project submissions and user-generated content using queues, filters, assignment, comments, and service-level indicators. | Must | +| ADM-003 | Users shall report a profile, project, blog, link, comment/evidence record, or security concern using structured reasons. | Must | +| ADM-004 | Moderation actions shall include no action, warning, content restriction, unpublish, account suspension, and escalation, each with reason and audit history. | Must | +| ADM-005 | Privileged search and exports shall be access-controlled, purpose-limited, logged, and protected from bulk misuse. | Must | +| ADM-006 | Super Admin shall view operational dashboards for active projects, stale projects, response SLA, sync failures, reports, security alerts, and adoption metrics. | Should | +| ADM-007 | The platform shall provide data correction, appeal, and content reinstatement workflows. | Should | +| ADM-008 | No privileged user shall be able to erase the audit record of their own action through the application interface. | Must | + +Table 7K. Analytics and reporting requirements + +| ID | Requirement | Priority | +|---------|-------------------------------------------------------------------------------------------------------------------------------------------------|--------------| +| ANL-001 | Analytics shall use documented event definitions and exclude authentication secrets, private repository content, and unnecessary personal data. | Must | +| ANL-002 | Ministry dashboards shall be restricted to the ministry's own projects and authorized cross-government aggregates. | Must | +| ANL-003 | Public reporting shall use aggregation and suppression thresholds to prevent identification of members in small groups. | Must | +| ANL-004 | Exports shall include source, generation time, filters, field definitions, and license/usage notice. | Should | +| ANL-005 | A public read-only API for approved project metadata may be introduced after security, rate-limit, privacy, and open-data review. | Could | + +# 8. Business Rules +Core business rules + +| ID | Rule | +|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| BR-001 | Only Super Admin-approved government projects may display official ministry identity or Government of Nepal endorsement. | +| BR-002 | A project cannot be published without a named ministry owner, public maintainer/contact path, approved contribution mode, response expectation, and suitability clearance. | +| BR-003 | A government repository must have an approved license, README, CONTRIBUTING guide, code of conduct, security reporting path, issue/task entry point, and branch/review controls before the project is marked ready. | +| BR-004 | A member's self-declared skills and education are not treated as government-verified credentials unless a separate verification process is approved. | +| BR-005 | GitHub's contribution graph and DevNepal's verified contribution record are different measures and must be labeled separately \[R5\]. | +| BR-006 | A contribution is official only after an authoritative repository event or authorized maintainer acceptance; self-submission alone is evidence, not verification. | +| BR-007 | A ministry maintainer may not award credit to themselves without secondary approval or an automated authoritative event. | +| BR-008 | Deleting/unpublishing a project does not erase audit, security, or contribution evidence that policy requires retaining. | +| BR-009 | Personal projects and personal blogs must not use official seals, logos, or wording in a way that implies government endorsement. | +| BR-010 | Content takedown, suspension, and leaderboard correction must use defined reasons and an appeal path except during urgent security containment. | +| BR-011 | A paused, completed, cancelled, or archived project does not accept new applications; existing records remain visible according to permissions. | +| BR-012 | Taxonomy and scoring-rule changes are versioned and must not silently rewrite historical meaning. | + +# 9. Information and Data Requirements +## 9.1 Core entities +Logical information model + +| Entity | Purpose / key relationships | +|-----------------------------|-------------------------------------------------------------------------------------------------------------------------------| +| User | Internal identity; roles, status, sessions, consent, and audit relationships. | +| Member profile | Public/private profile fields, skills, education, interests, links, preferences, and visibility. | +| Ministry organization | Official identity, status, contacts, publisher assignments, and owned government projects. | +| Project | Common project record with type = government or personal; owner, metadata, status, links, documents, tags, and milestones. | +| Project version / review | Immutable snapshot, submission decision, reviewer comment, and approval provenance. | +| Application / participation | Member-to-project relationship, screening response, status, assignment, and timeline. | +| Contribution record | Evidence, source event, project, member, type, impact tier, verification state, verifier, and recognition outcome. | +| Repository connection | GitHub installation, repository ID, granted scope, sync state, cursor, and health. | +| Provider event | Webhook/reconciliation payload reference, event ID, signature result, delivery time, processing state, and deduplication key. | +| Blog post | Author, content, safe rendered form, language, tags, moderation state, versions, and external canonical URL. | +| Recognition / badge | Criteria version, evidence, issuer, issue/revocation state, and visibility. | +| Notification | Recipient, type, channel, delivery state, read state, and template version. | +| Report / moderation case | Reporter, target, reason, evidence, assignment, decision, appeal, and audit trail. | +| Audit event | Actor, action, object, before/after reference, timestamp, source, result, and correlation ID. | + +## 9.2 Data classification +Proposed handling classes; align with approved Government of Nepal policy before implementation + +| Class | Examples | Handling | +|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------| +| Public | Approved projects, public profiles, published blogs, public contribution acknowledgements. | Indexed and publicly available; integrity and moderation controls required. | +| Internal | Drafts, review comments, ministry analytics, non-public operational metrics. | Authenticated access; ministry/role boundaries; no public indexing. | +| Confidential | Private contact details, applications, moderation evidence, provider connections, security reports. | Need-to-know access, encryption, restricted logs/exports, defined retention. | +| Secret / credential | OAuth tokens, signing keys, session secrets, webhook secrets. | Dedicated secret storage, never displayed or logged, rotation and access audit. | +| Prohibited for DevNepal | Classified project information, production credentials, citizen records, source data containing PII, exploitable undisclosed vulnerabilities in public content. | Do not collect or publish; route to approved secure systems. | + +## 9.3 Retention and deletion +- A records schedule shall be approved for profiles, applications, contribution evidence, audit events, provider events, logs, backups, moderation cases, and security reports. + +- Public project history should remain available as a transparency record after completion, with personal data minimized. + +- OAuth tokens and provider secrets shall be deleted promptly on disconnect/revocation; derived public data shall be handled according to consent and retention notices. + +- Backups shall expire according to schedule and shall not become a method of indefinite retention. + +- Deletion requests and legal holds shall be recorded, authorized, and verifiable. + +# 10. Integration Requirements +External integration inventory + +| Integration | Purpose | Required controls | +|-----------------------------------|----------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------| +| GitHub App / APIs | Sign-in/connect, selected repository access, profile/activity import, verified events. | Least privilege, PKCE/state where applicable, expiring tokens, secret vault, signatures, idempotency, rate limits, reconciliation, uninstall handling. | +| Google identity | Optional member federated sign-in. | OIDC validation, approved redirect URIs, minimal claims, provider outage handling. | +| Facebook identity | Optional member federated sign-in if approved for production. | Privacy/security review, minimal claims, provider terms, disable-by-configuration. | +| Email service | Verification, workflow notifications, digests, security notices. | Approved sender domain, SPF/DKIM/DMARC, templates, unsubscribe rules, retry and bounce handling. | +| Object storage / malware scanning | Project documents, profile/blog media, evidence files. | Private-by-default buckets, signed access, type/size validation, scanning, quarantine, retention. | +| Observability / incident tools | Metrics, logs, traces, alerts, incident coordination. | PII/secret filtering, access control, retention, correlation IDs, alert ownership. | + +# 11. Non-Functional Requirements +Table 11A. Proposed non-functional requirements and acceptance targets + +| ID | Requirement | Priority | +|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| +| NFR-PERF-01 | Public pages should achieve Largest Contentful Paint <= 2.5 seconds at the 75th percentile on a representative Nepal 4G/mobile profile after the pilot baseline. | Should | +| NFR-PERF-02 | Read APIs should respond within 500 ms at p95 and write APIs within 1 second at p95 under the approved launch load, excluding third-party provider latency. | Should | +| NFR-PERF-03 | Webhook receipt shall acknowledge valid deliveries quickly and process asynchronously; verified project activity should appear within 5 minutes at p95 during normal operation. | Should | +| NFR-AVL-01 | The production service target shall be at least 99.5% monthly availability for the initial public release, excluding approved maintenance; higher targets may follow operational maturity. | Should | +| NFR-AVL-02 | No single application instance shall be required for service continuity; health checks, graceful degradation, and queued retry shall protect third-party outages. | Must | +| NFR-DR-01 | A proposed baseline is RPO <= 24 hours and RTO <= 8 hours for launch; PMO shall approve final targets after impact assessment. | Should | +| NFR-SCL-01 | The system shall scale independently for public reads, search, background synchronization, notifications, and file processing. | Should | +| NFR-A11Y-01 | The public and authenticated web experience shall conform to WCAG 2.2 Level AA and be tested with automated and manual methods \[R9\]. | Must | +| NFR-I18N-01 | The interface shall support English and Nepali, Unicode storage/search, language switching, locale-aware dates, and translation fallback without mixed or broken layouts. | Must | +| NFR-COMP-01 | The web application shall support the latest two stable versions of major evergreen desktop and mobile browsers, with a documented compatibility matrix. | Should | +| NFR-SEO-01 | Approved public content shall have stable canonical URLs, descriptive metadata, social sharing metadata, sitemap inclusion, and controlled indexing; drafts/private content shall be excluded. | Should | +| NFR-OBS-01 | Every request and background job shall have a correlation ID; metrics, logs, traces, and alerts shall identify failure without recording secrets or unnecessary personal data. | Must | +| NFR-MNT-01 | The product shall use documented APIs, migrations, configuration, runbooks, dependency ownership, and automated tests so that government teams can maintain it without a single vendor or individual. | Must | +| NFR-PORT-01 | From initial deployment, devNepal's application, databases, runtime configuration, file storage, logs, and backups shall be hosted exclusively within Government of Nepal facilities; the same requirement applies to applications developed through the devNepal programme. | Must | + +# 12. Security, Privacy and Legal Requirements +## 12.1 Security baseline +DevNepal is a public government platform with privileged publishing workflows and third-party integrations. Security requirements should be verified against a recognized application standard such as OWASP ASVS and integrated into the development lifecycle using NIST SSDF-style practices \[R10, R11\]. + +Table 12A. Security requirements + +| ID | Requirement | Priority | +|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| +| SEC-001 | Apply least privilege to users, services, repositories, databases, storage, and administrative tools; deny by default. | Must | +| SEC-002 | Encrypt network traffic with current TLS and encrypt sensitive data, backups, and secrets at rest using approved key management. | Must | +| SEC-003 | Protect OAuth/OIDC flows with validated redirect URIs, state, PKCE where applicable, issuer/audience validation, and secure token storage. | Must | +| SEC-004 | Use secure, HttpOnly, SameSite cookies; protect against CSRF, XSS, injection, SSRF, open redirect, path traversal, and unsafe deserialization. | Must | +| SEC-005 | Enforce object-level and function-level authorization on every API route, including ministry ownership and moderation actions, addressing API authorization risks highlighted by OWASP \[R12\]. | Must | +| SEC-006 | Rate-limit and monitor authentication, search, exports, reports, uploads, GitHub callbacks, webhooks, and other abuse-sensitive flows. | Must | +| SEC-007 | Validate file type by content, limit size/count, rename safely, scan for malware, quarantine failures, and prevent direct execution. | Must | +| SEC-008 | Keep tamper-evident audit records for privileged actions, security changes, approval decisions, data exports, and failed authorization. | Must | +| SEC-009 | Run automated unit, integration, authorization, SAST, dependency, secret, container, and DAST checks in CI; block release on defined severity thresholds. | Must | +| SEC-010 | Generate and retain a software bill of materials using an approved standard such as SPDX, which is an ISO/IEC standard for software component information \[R13\]. | Should | +| SEC-011 | Perform independent penetration testing before public launch and after major identity, authorization, upload, or integration changes. | Must | +| SEC-012 | Publish a vulnerability disclosure and security contact process; sensitive reports shall never be submitted through public project pages. | Must | +| SEC-013 | Define incident severity, on-call ownership, containment, provider-token revocation, evidence preservation, communications, recovery, and post-incident review. | Must | +| SEC-014 | Repository security posture checks, potentially including OpenSSF Scorecard signals, may inform readiness but shall not be treated as proof that code is secure \[R14\]. | Could | + +## 12.2 Privacy requirements +- Complete a privacy impact assessment and a data inventory before the production pilot. + +- Provide clear notices for account data, public profile fields, applications, GitHub synchronization, analytics, moderation, retention, and data sharing. + +- Use explicit, revocable consent for optional public fields and GitHub-derived displays; provider authorization alone is not a substitute for a clear DevNepal notice. + +- Minimize collection and avoid publishing contact information, education documents, private contribution details, IP addresses, or moderation evidence. + +- Implement access, correction, export, disconnect, and deletion request workflows with identity verification and documented exceptions. + +- Restrict production data access to authorized named personnel and log privileged access and exports. + +## 12.3 Nepal legal and policy review +Authorized counsel and policy owners must map the final design, terms, consent, records schedule, hosting, and public-release rules to applicable Nepal law and government policy. At minimum, the review should consider the Privacy Act, 2075; Electronic Transactions Act, 2063; Right to Information Act, 2064; National Cyber Security Policy, 2080; intellectual-property and copyright rules; government records rules; and any approved government enterprise architecture, interoperability, hosting, accessibility, and security directives \[R6, R7, R8\]. + +> **Legal boundary:** This document identifies review topics but does not interpret Nepal law. No project should be opened for public contribution until the owning ministry confirms it has authority and rights to publish the relevant code, documents, data, and task information. + +## 12.4 Open-source and contribution policy +- Every government repository shall use a PMO-approved license identified with an SPDX license identifier; the allowed list and default require legal approval \[R13\]. + +- Each repository shall publish README, LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, governance/decision guidance, maintainers, release information, and project metadata. + +- PMO shall choose and publish a contributor-signoff model. A Developer Certificate of Origin-style sign-off is recommended for low-friction contribution, subject to legal approval; projects needing assignment or special rights may require a CLA. + +- Third-party dependencies, generated assets, data, fonts, models, and documentation shall be checked for compatible rights before release. + +- Security-sensitive components may use controlled contribution or disclosure workflows even when the broader project is open. + +# 13. Community and Content Governance +## 13.1 Required policies +- Terms of use and acceptable-use policy. + +- Privacy notice and cookie/analytics notice. + +- Community code of conduct with reporting, enforcement, confidentiality, and appeal procedures. + +- Government project publication and suitability policy. + +- Open-source license and contributor-signoff policy. + +- Content moderation, takedown, impersonation, unsafe-link, copyright, and repeat-abuse policy. + +- Leaderboard, badge, correction, and anti-gaming policy. + +- Vulnerability disclosure and incident communication policy. + +- Records retention, deletion, and public archive policy. + +Open-source community guidance recommends visible goals, contribution guidance, governance, and a code of conduct to support constructive participation \[R2, R15\]. + +## 13.2 Moderation principles +- Use the least restrictive action that protects people, the platform, and public trust. + +- Separate routine content quality review from security incident handling and legal takedown requests. + +- Give the affected user a reason and appeal path unless disclosure would create a security, legal, or safety risk. + +- Protect reporters and sensitive evidence; public moderation summaries must not expose them. + +- Use documented service levels and escalation for urgent threats, impersonation, malicious files/links, and vulnerable code disclosures. + +# 14. User Experience, Accessibility and Localization +## 14.1 Primary navigation +Recommended public information architecture + +| Area | Purpose | +|---------------------------|--------------------------------------------------------------------------------------------------| +| Home | Mission, featured government projects, contribution paths, impact, and trust signals. | +| Government Projects | Search and filter approved ministry opportunities. | +| Community Projects | Browse member-owned projects, clearly separated from official projects. | +| Members | Discover public member profiles by skills/interests where members opt in. | +| Tech Blogs | Browse technical writing by topic, language, author, and project. | +| Leaderboard / Recognition | Transparent verified-impact views and badge criteria. | +| About / How to Contribute | Mission, process, policies, FAQ, support, code of conduct, and security contact. | +| Dashboard | Role-specific tasks, drafts, applications, bookmarks, notifications, sync health, and analytics. | + +## 14.2 Accessibility requirements +- Meet WCAG 2.2 Level AA for public and authenticated workflows, including keyboard operation, focus visibility, contrast, labels, error recovery, target size, and accessible authentication \[R9\]. + +- Use semantic headings, landmarks, accessible names, descriptive links, captions/transcripts where needed, and alternative text for meaningful images. + +- Do not use color alone for status, contribution heatmaps, or leaderboard changes; provide text/values and high-contrast modes. + +- Ensure Markdown-generated blogs and ministry attachments follow accessible authoring guidance and validation. + +- Test with keyboard-only use, screen readers, zoom/reflow, reduced motion, Nepali content, and low-bandwidth/mobile conditions. + +## 14.3 Bilingual and low-bandwidth behavior +- All platform-owned interface text, validation, core policies, and help shall be available in Nepali and English at launch. + +- Government project title and summary should be required in both languages; long descriptions/documents may declare one or both languages until translation capacity is established. + +- Search shall match Devanagari and Latin text without corrupting slugs, highlights, or sorting. + +- Pages shall remain usable with images disabled or delayed; media shall be optimized, lazy-loaded, and sized responsively. + +- Critical actions shall not depend on animation, hover, drag-only interaction, or high-speed connectivity. + +# 15. Delivery Scope and Phasing +## 15.1 Phase 0 - policy, discovery and design readiness +- Confirm mandate, product owner, steering committee, participating pilot ministries, project-suitability policy, legal/privacy owners, and hosting authority. + +- Validate user journeys with ministry publishers, maintainers, students, experienced developers, non-code contributors, moderators, and people using assistive technology. + +- Approve data classification, retention, authentication, GitHub App permissions, repository baseline, licenses, contributor agreement, code of conduct, moderation, metrics, and bilingual content model. + +- Prototype and test project publication, discovery, first contribution, verification, and ministry response workflows before full build. + +## 15.2 Phase 1 - production MVP +- Three-role authorization with named ministry users, MFA, audit, consent, and account lifecycle. + +- Member profiles, skills, education, links, privacy controls, personal projects, and GitHub connection. + +- Government project lifecycle, attachments, review, publication, search/filter, bookmarks, application/direct-contribution modes, and updates. + +- GitHub App for selected repositories, secure webhooks, reconciliation, verified contribution records, and sync health. + +- Safe technical blogs, reporting/moderation, basic badges, and a conservative verified-contribution leaderboard. + +- Notifications, role dashboards, bilingual UI, accessibility, analytics, operational monitoring, backups, security testing, and support runbooks. + +## 15.3 Phase 2 - ecosystem maturity +- Mentorship cohorts, events/hackathons, team formation, contributor onboarding checklists, and richer recognition. + +- Repository readiness automation, public-code metadata validation, security posture signals, and improved project health dashboards. + +- Advanced content workflow, editorial curation, external article import where rights and APIs permit, and multilingual authoring support. + +- Public project metadata API/open-data export, integrations with approved government portals, and deeper outcome reporting. + +## 15.4 Phase 3 - optional capabilities +- Explainable project/member matching based on approved criteria and measured fairness. + +- Credential or certificate integrations, subject to identity, fraud, and legal review. + +- Native mobile experience only if web usage evidence demonstrates a material unmet need. + +- Cross-platform repository providers beyond GitHub based on demand and integration feasibility. + +## 15.5 Indicative delivery approach +Use incremental releases: internal alpha, ministry pilot, invited developer beta, public beta, and general availability. Calendar and budget estimates require confirmed team capacity and technology decisions; they should not be committed from this scope document alone. Each gate should include usability, accessibility, security, privacy, content readiness, operations, and support criteria. + +# 16. Acceptance and Readiness +## 16.1 Critical end-to-end acceptance scenarios +Launch-critical scenarios + +| ID | Acceptance scenario | +|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| A1 | Super Admin provisions a ministry and two named publishers; MFA is enforced; one publisher is revoked without affecting the other; all actions are audited. | +| A2 | A ministry drafts a bilingual project with repository, license, contribution guide, maintainer, milestones, suitability fields, and attachments; Super Admin requests changes; the ministry resubmits; approval publishes exactly the approved version. | +| A3 | A member signs in, configures public profile visibility, connects GitHub with limited scope, lists a personal project, and disconnects GitHub; sync stops and tokens are removed. | +| A4 | A member finds a project through Nepali and English search, applies or starts an open task, receives status updates, and sees an auditable timeline. | +| A5 | A signed GitHub webhook for a merged pull request creates one candidate contribution; duplicate delivery creates no duplicate; the maintainer verifies the result; recognition updates; revocation reverses it with an audit reason. | +| A6 | A member submits approved non-code contribution evidence; an authorized maintainer accepts it; the profile credits the correct contribution type without requiring a Git commit. | +| A7 | A malicious blog payload and unsafe file/link are rejected or sanitized; the moderation report reaches the correct queue without exposing evidence publicly. | +| A8 | A keyboard and screen-reader user completes registration, project search, application, blog reading, and account settings in Nepali and English with no critical WCAG failures. | +| A9 | A GitHub outage does not block public browsing; queued sync resumes without data loss or duplicate credit when service returns. | +| A10 | Backup restoration meets the approved RPO/RTO in a documented exercise and security/operations contacts can execute the incident runbook. | + +## 16.2 Production readiness checklist +- Business owner signs off scope, policies, project suitability, pilot ministries, metrics, and support model. + +- Security threat model, ASVS-based verification, dependency/SBOM checks, penetration test, and remediation are complete. + +- Privacy impact assessment, notices, consent, retention, data-subject workflows, and legal review are approved. + +- WCAG 2.2 AA audit and bilingual content QA are complete with no unresolved critical defects. + +- Backup/restore, disaster recovery, provider outage, webhook replay, incident response, and privileged-account revocation are tested. + +- Ministry maintainers and Super Admins are trained; runbooks, escalation, moderation, and communication templates are available. + +- At least a small set of real, contribution-ready pilot projects has active maintainers and starter tasks; the platform must not launch as an empty directory. + +# 17. Risks and Mitigations +Principal delivery and operating risks + +| Risk | Impact | Primary mitigation | +|-------------------------------------------------------|----------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------| +| Projects are published but maintainers do not respond | Volunteer trust collapses and listings become stale. | Require named maintainers, response SLA, readiness review, reminders, stale flags, escalation, pause/archive controls. | +| Sensitive project/data is exposed | Security, legal, and public-trust harm. | Suitability checklist, data classification, two-person approval for high-risk changes, no production data, security review. | +| Leaderboard rewards spam | Low-quality contributions and unfair recognition. | Accepted-impact records, no raw commit score, caps, anomaly review, transparent rules, reversals and opt-out. | +| GitHub API limits or outages | Stale profiles and contribution records. | Webhooks, queues, reconciliation, caching, backoff, rate monitoring, freshness labels, graceful degradation. | +| Shared ministry credentials | No accountability and high compromise risk. | Named accounts, MFA, provisioning/revocation, session controls, audit and training. | +| Legal/rights ambiguity | Government cannot safely publish or reuse contributions. | Approved licenses, rights checklist, contributor sign-off, dependency review, legal owner, project-by-project clearance. | +| Platform becomes a social/job site | Scope creep, moderation load, mission dilution. | Clear scope, no direct messaging/jobs/payments in MVP, roadmap governance, outcome metrics. | +| Underrepresentation outside major cities | National community goal is not achieved. | Mobile/low-bandwidth design, bilingual outreach, partnerships, remote contribution, privacy-safe regional metrics. | +| Toxic behavior or harassment | Contributor harm and community attrition. | Code of conduct, confidential reporting, trained moderators, sanctions, appeals, safety escalation. | +| Vendor/individual lock-in | Unsustainable operations and high transition cost. | Open standards, documented code/configuration, infrastructure-as-code, runbooks, data export, government ownership and training. | + +# 18. Assumptions, Dependencies and Decisions Required +## 18.1 Assumptions +- DevNepal is sponsored by PMO and participating ministries will designate accountable project owners and maintainers. + +- Only contribution-suitable public projects are listed; DevNepal does not grant volunteers access to production systems or sensitive citizen data. + +- GitHub is the primary source-code collaboration platform for the initial release, but DevNepal remains conceptually provider-neutral. + +- Government projects and community projects remain visually and logically distinct. + +- The initial product is a responsive web application with English and Nepali support. + +- Final legal, hosting, security, identity, retention, licensing, and branding decisions will be made by authorized Government of Nepal stakeholders. + +## 18.2 External dependencies +- PMO governance, product ownership, ministry participation, and timely approval decisions. + +- Named ministry maintainers with enough time to review and respond to contributions. + +- Approved GitHub organization/repository ownership and ability to install a GitHub App. + +- Approved identity providers, government sender domain/email service, hosting, monitoring, storage, secret management, and malware scanning. + +- Legal/privacy/security review capacity and approved public policies. + +- Bilingual content, translation, accessibility testing, community moderation, training, and launch communications. + +## 18.3 Decisions required before build commitment +Decision register with recommended starting position + +| Decision | Recommended starting position | Owner | +|---------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|------------------------------| +| Ministry identity model | One ministry organization with multiple named publisher accounts; never shared credentials. | PMO / security | +| Member sign-in providers | GitHub and Google for MVP; enable Facebook only after privacy/security/operational approval. | Product / privacy / security | +| GitHub synchronization boundary | Verified events from selected listed repositories; optional annual public contribution calendar with consent; no full private-history mirror. | Product / security | +| Official recognition | Accepted impact, including non-code work; no raw commit leaderboard. | Steering committee | +| Government project license | Use a small approved SPDX allowlist and documented default after legal review; do not allow free-text licenses. | Legal / policy | +| Contributor agreement | Use low-friction DCO-style sign-off where legally sufficient; CLA only where rights/policy require it. | Legal / open-source lead | +| Hosting and data residency | Approved government-controlled production environment with managed secrets, backups, monitoring, and disaster recovery. | PMO / MoCIT / DoIT / NITC | +| Project approval | Super Admin approval plus specialist security/legal review triggers based on risk fields. | PMO | +| Bilingual content | Bilingual UI and project title/summary at launch; allow declared-language long documents with translation roadmap. | Product / communications | +| Leaderboard launch | Pilot privately first; publish only after anti-gaming, opt-out, appeals, and scoring policy are validated. | Product / community | +| Public member directory | Opt-in discoverability; public profile visibility controlled field by field. | Privacy / product | +| Retention schedule | Approve before pilot using purpose-based periods and separate rules for audit/security records. | Records / legal / privacy | + +# Appendix A. Project Field Specification +Government project fields + +| Field group | Required information | +|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------| +| Identity | Project ID, type, title (English/Nepali), slug, ministry, owner, maintainers, official badge. | +| Public value | Problem statement, target users, expected public/institutional outcome, success indicators. | +| Description | Short summary, detailed description, background, current state, limitations, related initiatives. | +| Contribution need | Workstreams, contribution types, skills, technologies, difficulty, experience, estimated effort, capacity, location/remote, deadline. | +| How to contribute | Contribution mode, prerequisites, starter tasks/issues, communication channel, application questions, response SLA, code of conduct. | +| Technical | Repository/provider, default branch, issue tracker, documentation, architecture, environments, test/build instructions, CI status. | +| Governance | Decision model, maintainers, review/merge authority, ownership of outcomes, escalation, completion criteria. | +| Rights | Approved license/SPDX ID, contributor sign-off model, third-party rights confirmation, content/data license. | +| Security and data | Public-suitability confirmation, data classification, security contact, vulnerability disclosure path, prohibited data/access statement. | +| Planning | Status, dates, milestones, dependencies, risks, version/release links, progress updates. | +| Attachments | Proposal, requirements, architecture, design, API documentation, research, terms; version, language, accessibility, and classification metadata. | +| Closure | Outcome summary, deliverables/releases, impact, lessons, credited contributors, archive reason/date. | + +# Appendix B. Recommended Repository Readiness Checklist +- Public repository ownership is verified and the ministry has rights to publish the code and documentation. + +- README states the problem, status, setup, architecture entry point, roadmap, and public-value outcome. + +- LICENSE uses an approved SPDX identifier and matches dependency and asset rights. + +- CONTRIBUTING explains setup, issue selection, branch/PR process, testing, review, sign-off, response expectations, and communication. + +- CODE_OF_CONDUCT, SECURITY, maintainers/owners, governance, support boundaries, and release process are present. + +- Starter issues are labeled and small enough for onboarding; issue templates ask for safe, useful information. + +- Protected branches, required review, automated tests, secret scanning, dependency updates, least-privilege workflows, and release integrity controls are configured. + +- No credentials, citizen data, private endpoints, security-sensitive configurations, proprietary code, or incompatible assets are present. + +- Build/test instructions work from a clean environment and accessibility/localization requirements are documented where relevant. + +- Named maintainers have confirmed capacity to respond and verify contributions during the listing period. + +# Appendix C. Research Sources +*Sources inform recommended practices and integration constraints. They do not replace Government of Nepal legal or policy approval. Accessed 2 September 2026.* + +**R1. Digital.gov - Federal Source Code Policy summary.** [Open source](https://digital.gov/resources/requirements-for-achieving-efficiency-transparency-and-innovation-through-reusable-and-open-source-software/) + +**R2. Standard for Public Code - Make contributing easy.** [Open source](https://standard.publiccode.net/criteria/make-contributing-easy.html) + +**R3. GitHub Docs - Choosing permissions for a GitHub App.** [Open source](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app) + +**R4. GitHub Docs - Using webhooks with GitHub Apps.** [Open source](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/using-webhooks-with-github-apps) + +**R5. GitHub Docs - Profile contributions reference.** [Open source](https://docs.github.com/en/account-and-profile/reference/profile-contributions-reference) + +**R6. Nepal Law Commission - Privacy Act, 2075.** [Open source](https://lawcommission.gov.np/content/12261/12261-the-privacy-act-2075/) + +**R7. Nepal Law Commission - Electronic Transactions Act, 2063.** [Open source](https://lawcommission.gov.np/content/13397/) + +**R8. MoCIT - National Cyber Security Policy, 2080.** [Open source](https://mocit.gov.np/content/7119/7119-national-cyber-security-policy/) + +**R9. W3C - Web Content Accessibility Guidelines (WCAG) 2.2.** [Open source](https://www.w3.org/TR/WCAG22/) + +**R10. NIST SP 800-218 - Secure Software Development Framework 1.1.** [Open source](https://csrc.nist.gov/pubs/sp/800/218/final) + +**R11. OWASP - Application Security Verification Standard.** [Open source](https://owasp.org/www-project-application-security-verification-standard/) + +**R12. OWASP - API Security Top 10 (2023).** [Open source](https://owasp.org/API-Security/editions/2023/en/0x11-t10/) + +**R13. SPDX - Software Package Data Exchange standard.** [Open source](https://spdx.dev/) + +**R14. OpenSSF - Scorecard.** [Open source](https://scorecard.dev/) + +**R15. GitHub Open Source Guides - Starting a project, governance, community, and code of conduct.** [Open source](https://opensource.guide/) + +**R16. Nepal Law Commission - Right to Information Act, 2064.** [Open source](https://lawcommission.gov.np/content/13400/rights-of-information-act--2064/) + +# Appendix D. Glossary +| Term | Meaning in this document | +|-----------------------|------------------------------------------------------------------------------------------------------------------------------------| +| Accepted contribution | A code or non-code contribution approved by an authoritative maintainer or verified by an authoritative repository event. | +| Contribution evidence | A GitHub event, file, link, review record, or ministry attestation submitted to support verification. | +| GitHub App | A GitHub integration with explicit permissions, repository installations, short-lived tokens, and webhooks. | +| Member | A registered volunteer/community user who may maintain a profile, projects, blogs, and contribution history. | +| Ministry Publisher | A named government officer authorized to act for an assigned ministry organization in DevNepal. | +| Project suitability | Confirmation that a government project is legally, operationally, technically, and security-appropriate for public contribution. | +| Super Admin | The highest platform role responsible for ministry provisioning, project approval, moderation, configuration, and audit oversight. | +| Verified contribution | An accepted contribution whose source, project, contributor mapping, and approval provenance are recorded. | + +# End of Document +> **Next action:** PMO should hold a requirements validation workshop with the product owner, at least two pilot ministries, security/privacy/legal reviewers, repository maintainers, and representative contributors. Resolve the decision register, update this document to version 1.0, and then derive the product backlog, system architecture, delivery estimate, and test plan.