From 3136c97314774f828338947783d63361403d0108 Mon Sep 17 00:00:00 2001 From: Yongcheng Wu Date: Sat, 11 Jul 2026 22:18:18 +0800 Subject: [PATCH 1/2] fix(*): add extra blank line before the first entry in list --- docs/appendices/group-policies.md | 2 ++ docs/appendices/research-software-principles.md | 7 +++++++ docs/maintainer/01-repo-creation.md | 2 ++ docs/maintainer/03-branch-protection.md | 2 ++ docs/maintainer/04-collaborators.md | 2 ++ docs/maintainer/05-labels.md | 3 +++ docs/maintainer/06-milestones.md | 4 ++++ docs/maintainer/07-project-board.md | 2 ++ docs/maintainer/08-review-workflow.md | 4 ++++ docs/maintainer/09-merge-strategy.md | 1 + docs/maintainer/10-releases.md | 7 +++++++ docs/maintainer/12-documentation-policy.md | 4 ++++ docs/maintainer/13-testing-policy.md | 3 +++ docs/maintainer/14-ci-preparation.md | 5 +++++ docs/maintainer/15-backup-strategy.md | 2 ++ docs/maintainer/16-archiving.md | 2 ++ docs/maintainer/18-student-onboarding.md | 1 + docs/maintainer/19-student-offboarding.md | 6 ++++++ docs/student/01-introduction.md | 4 ++++ docs/student/02-git-vs-github.md | 4 ++++ docs/student/03-workflow-overview.md | 3 +++ docs/student/04-initial-setup.md | 2 ++ docs/student/05-ssh.md | 2 ++ docs/student/07-daily-workflow.md | 5 +++++ docs/student/08-branches.md | 4 ++++ docs/student/09-commits.md | 2 ++ docs/student/10-push.md | 1 + docs/student/11-pull-requests.md | 5 +++++ docs/student/12-reviews.md | 9 +++++++++ docs/student/13-merge-conflicts.md | 2 ++ docs/student/16-faq.md | 1 + docs/student/18-exercises.md | 15 +++++++++++++++ docs/templates/release-checklist.md | 1 + 33 files changed, 119 insertions(+) diff --git a/docs/appendices/group-policies.md b/docs/appendices/group-policies.md index a7ebf1e..4bf46a8 100644 --- a/docs/appendices/group-policies.md +++ b/docs/appendices/group-policies.md @@ -22,6 +22,7 @@ Examples: `phase-transition-solver`, `gw-spectrum-calculator-py`. ### R3 — Required Files Every repository must contain at the time of first collaborator access: + - `README.md` (using the group template) - `.gitignore` (appropriate for the primary language) - `LICENSE` (MIT unless the PI specifies otherwise) @@ -157,6 +158,7 @@ user-facing behaviour. Policies are updated via Pull Request to this handbook. Proposed policy changes must: + 1. Be discussed in a group meeting or in an Issue before opening a PR. 2. Be approved by the PI. 3. Be communicated to all active group members after merging. diff --git a/docs/appendices/research-software-principles.md b/docs/appendices/research-software-principles.md index ceb1044..5f4e5e8 100644 --- a/docs/appendices/research-software-principles.md +++ b/docs/appendices/research-software-principles.md @@ -30,6 +30,7 @@ paper that describes it. It deserves the same level of care, documentation, and peer review. Consequences: + - Code review is peer review, not gatekeeping. - A function without a citation to its source equation is incomplete. - "It works on my machine" is not scientific validation. @@ -65,6 +66,7 @@ Version control is not for programmers — it is for anyone who produces files that change over time and whose history matters. In this group, version control applies to: + - Simulation code - Analysis scripts - Figure-generation scripts @@ -73,6 +75,7 @@ In this group, version control applies to: - This handbook **Not** managed by the group's repositories: + - Raw experimental data (managed separately) - Large simulation outputs (referenced by path, not stored in Git) - Binary assets and generated figures (regenerated from code) @@ -85,6 +88,7 @@ Consistency across the group matters more than any individual's preferred workfl The canonical workflow in this handbook is not the only valid approach to Git. There are many legitimate alternatives. We use one because: + - Onboarding is faster when everyone does the same thing - Code review is easier when history has a predictable structure - Debugging is faster when `git log` is clean and squashed @@ -101,6 +105,7 @@ The minimum testing bar for research code is not code coverage percentage — it is: *can you trust the results enough to put them in a paper?* Practically, this means: + - Every numerical result that appears in a figure must have a test - Every equation implementation must be validated against a known special case - Every bug fix must be accompanied by a regression test @@ -116,6 +121,7 @@ future self. Documenting your work is an act of respect for your collaborators and the scientific community. Minimum documentation standards: + - Every function explains what it does and what its parameters mean - Every non-trivial algorithm cites its source - Every repository has a README that a newcomer can follow @@ -161,6 +167,7 @@ into a published figure. ## 10. The Handbook Is a Living Document This handbook describes current best practices. It will need to change as: + - The group grows - New tools become available - Current practices are found to be ineffective diff --git a/docs/maintainer/01-repo-creation.md b/docs/maintainer/01-repo-creation.md index 214588e..e52a4c4 100644 --- a/docs/maintainer/01-repo-creation.md +++ b/docs/maintainer/01-repo-creation.md @@ -75,6 +75,7 @@ A well-labelled repository is discoverable and professional. ``` physics cosmology phase-transition python research-code ``` + 3. Click **Save changes**. --- @@ -92,6 +93,7 @@ ls -la ``` Confirm: + - `.gitignore` is present and appropriate for the language - `README.md` is present - `LICENSE` is present diff --git a/docs/maintainer/03-branch-protection.md b/docs/maintainer/03-branch-protection.md index 2c117ff..c60e0f8 100644 --- a/docs/maintainer/03-branch-protection.md +++ b/docs/maintainer/03-branch-protection.md @@ -28,6 +28,7 @@ Configure the rule for the branch name pattern: `main` ✓ **Enable:** "Require a pull request before merging" Sub-options: + - **"Require approvals":** ✓ Enable — set to **1** (minimum; increase when group grows) - **"Dismiss stale pull request approvals when new commits are pushed":** ✓ Enable @@ -43,6 +44,7 @@ Sub-options: ✓ **Enable:** "Require status checks to pass before merging" Sub-options: + - **"Require branches to be up to date before merging":** ✓ Enable *Why:* Prevents a PR from merging if `main` has advanced since the PR branch diff --git a/docs/maintainer/04-collaborators.md b/docs/maintainer/04-collaborators.md index ea9c8ac..30da6ec 100644 --- a/docs/maintainer/04-collaborators.md +++ b/docs/maintainer/04-collaborators.md @@ -54,6 +54,7 @@ graph TD 5. GitHub sends an invitation email. The collaborator must accept within 7 days. Verify acceptance: + - Settings → Collaborators → look for "Pending" status - Follow up if pending for more than 2 business days @@ -100,6 +101,7 @@ Access for individual repository: **Repository → Insights → (not available) — use organisation audit log** Use the audit log to: + - Verify that a student accepted their invitation - Confirm who made a settings change - Investigate unexpected repository actions diff --git a/docs/maintainer/05-labels.md b/docs/maintainer/05-labels.md index 724f16f..98a2ac0 100644 --- a/docs/maintainer/05-labels.md +++ b/docs/maintainer/05-labels.md @@ -100,17 +100,20 @@ gh label create "status: stale" --color "cccccc" --description "No activity for ## Applying Labels Consistently **Labels on Issues:** + - Apply `type:` label when creating the issue - Apply `priority:` label if urgency is known - Apply `status:` as work progresses **Labels on Pull Requests:** + - Apply `type:` label to every PR (students should do this when opening the PR) - Apply `priority: high` for urgent fixes - Apply `status: needs-review` when the PR is ready for review - Remove `status: needs-review` and add `status: stale` if the PR goes cold **Periodic triage (recommended: weekly):** + - Review open issues and PRs without labels - Apply `status: stale` to anything with no activity for 30+ days - Prompt authors or close stale items diff --git a/docs/maintainer/06-milestones.md b/docs/maintainer/06-milestones.md index 28d75f9..b8af801 100644 --- a/docs/maintainer/06-milestones.md +++ b/docs/maintainer/06-milestones.md @@ -12,6 +12,7 @@ They are the primary tool for deadline-driven planning in the group. ## What Is a Milestone? A milestone has: + - A **title** (the goal) - An optional **description** (what done looks like) - A **due date** @@ -63,9 +64,11 @@ A milestone without a due date is just a label with extra steps. ## Assigning Issues and PRs to Milestones When opening or editing an Issue or PR: + - Right sidebar → **Milestone** → select the appropriate milestone For batch assignment: + - **Issues** → check multiple issues → **Milestone** dropdown **Policy:** Every issue and PR that must be completed before a deadline @@ -81,6 +84,7 @@ Navigate to **Issues → Milestones** to see all milestones and their completion The progress bar shows `X of Y issues/PRs closed`. Use this in group meetings to communicate: + - How much remains before the deadline - Which items are blocking progress - Whether the deadline is realistic diff --git a/docs/maintainer/07-project-board.md b/docs/maintainer/07-project-board.md index 19b58fe..d608840 100644 --- a/docs/maintainer/07-project-board.md +++ b/docs/maintainer/07-project-board.md @@ -52,10 +52,12 @@ Add these fields to track status alongside the default title/assignee: ## Linking Issues and PRs to the Board When creating an issue or PR: + - Right sidebar → **Projects** → select the board - Set the **Status** field to the appropriate column When work progresses, update the status: + - Created issue → **Backlog** - Work started, branch created → **In Progress** - PR opened → **In Review** diff --git a/docs/maintainer/08-review-workflow.md b/docs/maintainer/08-review-workflow.md index 2120165..3f07337 100644 --- a/docs/maintainer/08-review-workflow.md +++ b/docs/maintainer/08-review-workflow.md @@ -30,6 +30,7 @@ someone with Maintain or Admin permission. The group policy: **respond to a PR within 2 working days** of it being assigned. "Respond" means: + - Approve and merge, or - Leave at least one substantive comment and request changes, or - Leave a comment explaining a delay ("I'll review this by [date]") @@ -124,6 +125,7 @@ The maintainer merges the PR: 1. Confirm the branch is up to date with `main` (GitHub shows a warning if not). If not: ask the author to rebase, or click "Update branch" (merge) as a last resort. + 2. Confirm all conversations are resolved. 3. Confirm CI passes (once CI is active). 4. Click **"Squash and merge"**. @@ -133,6 +135,7 @@ The maintainer merges the PR: Optional: one-line context if the title is not fully self-explanatory. ``` + 6. Click **"Confirm squash and merge"**. 7. The remote branch is deleted automatically. @@ -143,6 +146,7 @@ The maintainer merges the PR: A PR is stale if the author has not responded to review feedback within 7 days. Steps: + 1. Leave a comment: *"Pinging @author — any update on this? Happy to help if you're stuck."* 2. Wait 3 more days. 3. If still no response: label `status: stale`. diff --git a/docs/maintainer/09-merge-strategy.md b/docs/maintainer/09-merge-strategy.md index 02c4392..0a7aafc 100644 --- a/docs/maintainer/09-merge-strategy.md +++ b/docs/maintainer/09-merge-strategy.md @@ -79,6 +79,7 @@ Update installation documentation (#71) ``` Rules: + - **Imperative tense** (same as individual commit messages) - **PR number in parentheses** at the end — links back to the PR discussion - **One line** is sufficient for the subject diff --git a/docs/maintainer/10-releases.md b/docs/maintainer/10-releases.md index 3fba535..ba9902c 100644 --- a/docs/maintainer/10-releases.md +++ b/docs/maintainer/10-releases.md @@ -12,6 +12,7 @@ presentations, and stable versions shared with collaborators. ## What Is a Release? A GitHub Release consists of: + - A **Git tag** (the specific commit being released) - A **title** (human-readable version name) - **Release notes** (what changed) @@ -44,6 +45,7 @@ All releases use **Semantic Versioning**: `MAJOR.MINOR.PATCH` | `PATCH` | Bug fixes, no new features | `1.0.0 → 1.0.1` | For research code: + - The **first stable, tested version** is `v1.0.0` - **New calculations added** → increment MINOR - **Bug fixes** → increment PATCH @@ -109,18 +111,22 @@ changed and why. Organise by category: This release corresponds to the code submitted with arXiv:XXXX.XXXXX. ### New Features + - Added one-loop thermal correction to effective potential (#42) - Added gravitational wave spectrum calculator (#51) ### Bug Fixes + - Fixed interpolation overflow at high temperature (#55) - Corrected sign error in bubble nucleation rate (#57) ### Documentation + - Updated installation instructions for macOS (#61) - Added worked example in docs/examples/ (#63) ### Breaking Changes + - `compute_potential()` now requires `include_thermal` keyword argument. Update existing code: `compute_potential(phi, T, include_thermal=False)` ``` @@ -131,6 +137,7 @@ This release corresponds to the code submitted with arXiv:XXXX.XXXXX. For most research code releases, the auto-generated source archive is sufficient. Attach additional assets only when: + - Pre-compiled binaries are provided for reproducibility - Large input data files are needed to run the code - A specific dataset snapshot is being archived with the release diff --git a/docs/maintainer/12-documentation-policy.md b/docs/maintainer/12-documentation-policy.md index 0b4e15a..ac6af55 100644 --- a/docs/maintainer/12-documentation-policy.md +++ b/docs/maintainer/12-documentation-policy.md @@ -17,6 +17,7 @@ This chapter defines the minimum documentation standards for all group repositor Every function or class that other code calls must have a docstring. The docstring must include: + - **Purpose:** what the function does in one sentence - **Parameters:** name, type, meaning, and expected range for each parameter - **Return value:** type and meaning @@ -72,6 +73,7 @@ double thermal_correction(double phi, double T, double g2); ### 2. Every Non-Obvious Algorithm Any non-trivial numerical method must include: + - A citation to the source paper or textbook - The equation number being implemented - Any assumptions or approximations made @@ -125,6 +127,7 @@ The README is the first thing a new user reads. It must accurately reflect the current state of the code. Review the README when: + - A new feature significantly changes usage - Installation instructions change - Dependencies are updated @@ -175,6 +178,7 @@ Documentation is part of the review checklist (Chapter 8). A PR that adds a function without a docstring should not be approved. Specifically check: + - [ ] New public functions have docstrings with parameter and return docs - [ ] Non-obvious algorithms reference their source equation/paper - [ ] New scripts have header comments with usage diff --git a/docs/maintainer/13-testing-policy.md b/docs/maintainer/13-testing-policy.md index f93f991..1c439b3 100644 --- a/docs/maintainer/13-testing-policy.md +++ b/docs/maintainer/13-testing-policy.md @@ -16,12 +16,14 @@ This chapter defines the minimum testing requirements for all group repositories **Not every line needs a test. Every result that gets published does.** The following must always have tests: + - Numerical solvers (regression tests with known outputs) - Any function whose output appears in a paper figure - Parser and file-loading functions (edge cases and malformed inputs) - Any function that is non-trivial to inspect visually The following does not need automated tests: + - Plotting and visualisation functions - One-time utility scripts - Simple file path manipulation @@ -117,6 +119,7 @@ tests/ **Test function naming:** `test__()` Examples: + - `test_thermal_correction_known_value()` - `test_thermal_correction_zero_temperature()` - `test_potential_minimum_location_at_T0()` diff --git a/docs/maintainer/14-ci-preparation.md b/docs/maintainer/14-ci-preparation.md index e308c3d..dcca0b3 100644 --- a/docs/maintainer/14-ci-preparation.md +++ b/docs/maintainer/14-ci-preparation.md @@ -13,11 +13,13 @@ This chapter prepares the repository for CI using GitHub Actions. ## What Is CI and Why the Group Needs It Without CI: + - Tests run only when someone remembers - "Tests pass" in the PR description is unverifiable - A broken `main` requires manual diagnosis With CI: + - Tests run automatically on every PR - A red ✗ on the PR blocks merge (once status checks are required in Chapter 3) - `main` is always in a tested state @@ -152,6 +154,7 @@ Add these workflows incrementally as the codebase matures: ### Code Style (flake8 / ruff) ```yaml + - name: Lint with ruff run: | pip install ruff @@ -161,6 +164,7 @@ Add these workflows incrementally as the codebase matures: ### Type Checking (mypy) ```yaml + - name: Type check with mypy run: | pip install mypy @@ -170,6 +174,7 @@ Add these workflows incrementally as the codebase matures: ### Documentation Build ```yaml + - name: Build MkDocs run: | pip install mkdocs-material diff --git a/docs/maintainer/15-backup-strategy.md b/docs/maintainer/15-backup-strategy.md index c432cf4..49d3c5d 100644 --- a/docs/maintainer/15-backup-strategy.md +++ b/docs/maintainer/15-backup-strategy.md @@ -28,6 +28,7 @@ history exist. The backup is only as good as the most recent push. All branches with meaningful work must be pushed to GitHub before: + - Extended absences (vacations, field work, conferences) - Leaving the group - Handing off a project @@ -97,6 +98,7 @@ git push --tags origin | Every month (active projects) | Recommended | Store bundles on: + - The group's institutional server (if available) - An external hard drive stored at the institute - A cloud storage service with access controlled by the PI diff --git a/docs/maintainer/16-archiving.md b/docs/maintainer/16-archiving.md index a029fd6..d759789 100644 --- a/docs/maintainer/16-archiving.md +++ b/docs/maintainer/16-archiving.md @@ -6,6 +6,7 @@ A repository should be archived when a project is complete: the paper is publish the code is stable, and no further active development is planned. Archiving is distinct from deletion. An archived repository: + - Remains accessible on GitHub - Is clearly marked as inactive (read-only) - Can be cloned and cited forever @@ -57,6 +58,7 @@ The release notes should include the paper DOI and a summary of what the code do ### 2. Update README The README should clearly state: + - The paper this code corresponds to (with full citation and DOI) - That the repository is archived and not actively maintained - Contact information for questions (PI email) diff --git a/docs/maintainer/18-student-onboarding.md b/docs/maintainer/18-student-onboarding.md index b1e456f..6b796b5 100644 --- a/docs/maintainer/18-student-onboarding.md +++ b/docs/maintainer/18-student-onboarding.md @@ -74,6 +74,7 @@ with the student. Have them: ## The First PR Review: A Teaching Moment Review the student's first PR yourself, leaving **pedagogical comments**: + - Point out what they did well - Explain (not just flag) any issues with commit message, PR description, etc. - Approve and merge together so they see the full cycle diff --git a/docs/maintainer/19-student-offboarding.md b/docs/maintainer/19-student-offboarding.md index a8c0827..7363a8c 100644 --- a/docs/maintainer/19-student-offboarding.md +++ b/docs/maintainer/19-student-offboarding.md @@ -54,6 +54,7 @@ For any significant in-progress work, the departing student must write a handoff This can be a comment on the relevant Issue or PR, or a short document in `docs/`: The note must include: + - Current state of the work - What has been done and what remains - Any non-obvious context (numerical subtleties, failed approaches, physics assumptions) @@ -103,6 +104,7 @@ Verify on GitHub that all expected branches and tags are present. ## Step 5: Final Knowledge Transfer Before access is revoked, have a 30-minute conversation covering: + - Status of all in-progress work - Any domain knowledge not documented in the code - Passwords or shared credentials that need to be rotated @@ -140,21 +142,25 @@ Their name will appear in `git log` forever — which is appropriate attribution ## Offboarding Checklist ### 2 Weeks Before + - [ ] All open PRs identified and action decided (merge, transfer, or close) - [ ] All open Issues reassigned - [ ] All active branches identified ### 1 Week Before + - [ ] In-progress branches committed and pushed - [ ] Handoff documentation written for significant unfinished work - [ ] Unmerged but valuable branches archived as tags ### Last Day + - [ ] All work pushed (`git push --all origin && git push --tags origin`) - [ ] Knowledge transfer conversation completed and notes taken - [ ] GitHub access revoked ### After Departure + - [ ] Student removed from communication channels - [ ] Any shared credentials rotated - [ ] Final backup created (git bundle) diff --git a/docs/student/01-introduction.md b/docs/student/01-introduction.md index 86bd826..25b33ea 100644 --- a/docs/student/01-introduction.md +++ b/docs/student/01-introduction.md @@ -26,10 +26,13 @@ Here are real situations that occur in research groups without version control: 2. **Untraceable results.** A figure in a submitted paper was generated by `run_v4_corrected2.py`, but no one remembers exactly which parameters were used at that moment. + 3. **Broken collaboration.** Two students edit the same file on different computers. One overwrites the other's changes by copying the file via email. + 4. **Fear of change.** Students avoid refactoring code because "what if something breaks?" Without version control, there is no safe way to experiment. + 5. **Irreproducible publications.** A reviewer asks for a modified figure. The code that produced the original figure has been changed, and the original cannot be recovered. @@ -106,6 +109,7 @@ The full glossary is in the Appendices. These terms appear immediately: 1. **Treating Git as a backup system.** Git is a collaboration and history tool. It tracks *meaningful changes*, not automatic saves. + 2. **Committing everything at once at the end.** Commit as you work, in logical units. 3. **Using Git only for code.** Version control is equally valuable for analysis scripts, parameter files, documentation, and figure-generation scripts. diff --git a/docs/student/02-git-vs-github.md b/docs/student/02-git-vs-github.md index d483f2d..1b39869 100644 --- a/docs/student/02-git-vs-github.md +++ b/docs/student/02-git-vs-github.md @@ -20,9 +20,11 @@ Key properties of Git: - **Local.** Git works entirely on your machine. No internet connection is needed to commit, branch, diff, or view history. + - **Distributed.** Every clone of a repository contains the complete history. There is no single "master copy" — although in practice, one remote serves as the canonical reference. + - **Free and open source.** Created by Linus Torvalds in 2005 for Linux kernel development. Git is installed as a command-line tool: @@ -118,8 +120,10 @@ In this group, GitHub serves as: 1. **Thinking "I pushed to Git."** You push to GitHub (the remote). Git is the local tool. Say "I pushed to GitHub" or "I pushed to origin." + 2. **Editing files directly on GitHub's web editor** for anything beyond trivial one-line fixes. Always work locally, then push. + 3. **Confusing `git pull` and `git clone`.** `clone` is a one-time operation to get a local copy. `pull` is used regularly to sync changes after you already have a clone. diff --git a/docs/student/03-workflow-overview.md b/docs/student/03-workflow-overview.md index 8fe9b43..9137dfa 100644 --- a/docs/student/03-workflow-overview.md +++ b/docs/student/03-workflow-overview.md @@ -149,10 +149,13 @@ This workflow is designed specifically for a **small research group** (3–10 de 1. **Working directly on `main`.** Even if branch protection were not enforced, this is wrong practice. Always create a branch. + 2. **One massive branch for everything.** Each branch should represent one focused task. Large branches are hard to review and hard to merge. + 3. **Not pulling before starting work.** If you start a branch from a stale `main`, your branch will diverge quickly and conflicts will accumulate. + 4. **Forgetting to delete the branch after merge.** Stale branches clutter the repository. --- diff --git a/docs/student/04-initial-setup.md b/docs/student/04-initial-setup.md index dc05396..c504d13 100644 --- a/docs/student/04-initial-setup.md +++ b/docs/student/04-initial-setup.md @@ -189,9 +189,11 @@ SSH setup is covered in the next chapter. You are not yet ready to push or pull. 1. **Using a personal email instead of the institute email.** Commits will not be linked to your GitHub profile correctly, and the group's audit records will be incomplete. + 2. **Skipping `user.email`.** Git will warn you on every commit. 3. **Not setting `init.defaultBranch main`.** New repositories will start on `master` instead of `main`, causing confusion. + 4. **Configuring at repository level instead of global.** Without `--global`, settings only apply to the current repository. Use `--global` for all identity settings. diff --git a/docs/student/05-ssh.md b/docs/student/05-ssh.md index b855f70..8c2f3af 100644 --- a/docs/student/05-ssh.md +++ b/docs/student/05-ssh.md @@ -31,6 +31,7 @@ ls -la ~/.ssh ``` Look for files named: + - `id_ed25519` and `id_ed25519.pub` (recommended) - `id_rsa` and `id_rsa.pub` (older, acceptable) @@ -219,6 +220,7 @@ If `ssh -T git@github.com` does not return your username: 1. **Uploading the private key** (`id_ed25519` without `.pub`) to GitHub. This is a serious security error. Delete the key from GitHub immediately and generate a new key pair. + 2. **Forgetting to start `ssh-agent`.** The key must be loaded into the agent. 3. **One key for multiple people.** Every person must have their own key. 4. **Copying only part of the public key.** The entire `.pub` file content diff --git a/docs/student/07-daily-workflow.md b/docs/student/07-daily-workflow.md index 0e0d3ae..a05d963 100644 --- a/docs/student/07-daily-workflow.md +++ b/docs/student/07-daily-workflow.md @@ -58,6 +58,7 @@ git checkout -b feature/describe-your-task ``` This command: + 1. Creates a new branch named `feature/describe-your-task` 2. Switches you to that branch immediately @@ -300,12 +301,16 @@ setting "Automatically delete head branches" is enabled). 1. **Skipping `git pull` at the start of the day.** Your branch will be based on a stale `main` and accumulate conflicts. + 2. **Committing everything in one giant commit.** This makes review difficult and makes it impossible to trace when a bug was introduced. + 3. **Staging with `git add .` without checking `git status` first.** You may accidentally commit generated files or temporary files. + 4. **Working on `main` instead of a feature branch.** Git may allow this locally, but your push to `main` will be rejected by branch protection. + 5. **Forgetting to push before opening the PR.** The PR cannot be created if the branch is not on GitHub. diff --git a/docs/student/08-branches.md b/docs/student/08-branches.md index c142b6b..4aaca64 100644 --- a/docs/student/08-branches.md +++ b/docs/student/08-branches.md @@ -33,6 +33,7 @@ gitGraph ``` In this diagram: + - `main` advanced from C to F while `feature/thermal-correction` was being developed. - `feature/thermal-correction` contains commits D and E that `main` does not (yet) have. - Neither branch is "ahead" — they just diverged from commit C. @@ -66,6 +67,7 @@ All lowercase, hyphens for spaces, no special characters. | `chore/` | Build system, CI, tooling, dependencies | `chore/update-dependencies` | **Rules:** + - Use lowercase only - Use hyphens, not underscores or spaces - Be descriptive — `feature/gw-spectrum` is better than `feature/new-stuff` @@ -97,6 +99,7 @@ git branch Output: ``` + * feature/my-task main ``` @@ -166,6 +169,7 @@ This replays your commits on top of the latest `main`. **Never reuse an old branch for a new task.** After a branch is merged: + 1. Delete it locally: `git branch -d feature/old-task` 2. Start fresh: `git checkout main && git pull origin main && git checkout -b feature/new-task` diff --git a/docs/student/09-commits.md b/docs/student/09-commits.md index 7500862..99ab953 100644 --- a/docs/student/09-commits.md +++ b/docs/student/09-commits.md @@ -50,12 +50,14 @@ Closes #42. ``` **Subject line rules:** + - Use the **imperative mood**: "Add", "Fix", "Remove", "Improve", "Refactor" - Maximum 72 characters - No period at the end - Describe *what* the commit does, not *how* **Body rules (optional but valuable):** + - Leave a blank line between subject and body - Explain *why* the change was made - Reference relevant equations, papers, or issue numbers diff --git a/docs/student/10-push.md b/docs/student/10-push.md index 2502802..f9b4c16 100644 --- a/docs/student/10-push.md +++ b/docs/student/10-push.md @@ -123,6 +123,7 @@ git push --force-with-lease `--force` provides no such protection. Never use it. **Rules for force push:** + - ✓ Your own feature branch, before or during review - ✓ After `git rebase origin/main` on your own branch - ✗ Never force-push to `main` (blocked by branch protection) diff --git a/docs/student/11-pull-requests.md b/docs/student/11-pull-requests.md index 122bfea..4124ef8 100644 --- a/docs/student/11-pull-requests.md +++ b/docs/student/11-pull-requests.md @@ -42,6 +42,7 @@ After pushing your branch: 1. Go to the repository on GitHub. 2. Click **"Compare & pull request"** in the yellow banner, or go to **Pull Requests → New pull request**. + 3. Verify: - **Base branch:** `main` - **Compare branch:** your feature branch @@ -66,11 +67,13 @@ causing incorrect phase boundary predictions at T > 0. ## Summary of Changes + - Added `thermal_correction()` function in `src/thermal.py` - Integrated the correction into `EffectivePotential.compute()` - Added unit tests in `tests/test_thermal.py` ## Files Affected + - `src/thermal.py` (new file) - `src/potential.py` (modified: integrate thermal correction) - `tests/test_thermal.py` (new file) @@ -100,6 +103,7 @@ The title should complete: "If merged, this PR will ___." In the right sidebar of the PR page, click **Reviewers** and select a group member. Group policy: + - Every PR requires **at least one approval** before it can be merged. - Assign the reviewer who is most familiar with the code area you changed. - If unsure who to assign, ask the maintainer. @@ -176,6 +180,7 @@ A PR that changes 500 lines may sit unreviewed for days because no one wants to tackle it. Guidelines: + - **One PR per feature or bug fix** — do not bundle unrelated changes. - If your task is large, split it into sequential PRs. - A PR touching more than 300 lines (excluding tests and docs) should be discussed diff --git a/docs/student/12-reviews.md b/docs/student/12-reviews.md index d0f3607..2a95e7f 100644 --- a/docs/student/12-reviews.md +++ b/docs/student/12-reviews.md @@ -48,6 +48,7 @@ When leaving feedback as a reviewer, label your intent: 5. If you disagree with a suggestion, say so politely with reasoning: > "I considered this, but the list comprehension version is harder to debug > because it hides the intermediate step. I'll keep the loop for now." + 6. After addressing all feedback, request a re-review. **Keep replies brief and professional.** A two-sentence explanation is usually sufficient. @@ -59,12 +60,14 @@ When leaving feedback as a reviewer, label your intent: When you are the reviewer, evaluate the PR against this checklist: ### Scientific Correctness + - [ ] The mathematical derivation or physical model is correct. - [ ] Equations are implemented as described (check against the paper or derivation). - [ ] Numerical parameters (tolerances, step sizes) are physically reasonable. - [ ] Edge cases are handled (zero temperature, zero field, singular limits). ### Code Quality + - [ ] The code is readable — someone unfamiliar can understand it. - [ ] Variable and function names are descriptive. - [ ] No code duplication that should be a function. @@ -72,16 +75,19 @@ When you are the reviewer, evaluate the PR against this checklist: - [ ] No debug output (`print` statements, `breakpoint()` calls) left in. ### Tests + - [ ] New functionality has tests. - [ ] Tests cover edge cases, not just the happy path. - [ ] Existing tests still pass. ### Documentation + - [ ] New functions have docstrings (where the codebase uses them). - [ ] The CHANGELOG or PR description explains what changed and why. - [ ] No broken links or outdated descriptions. ### Repository Hygiene + - [ ] No generated files committed (`.pyc`, `__pycache__`, output figures). - [ ] No large data files committed. - [ ] No credentials or secrets. @@ -108,13 +114,16 @@ When you are the reviewer, evaluate the PR against this checklist: ## Review Etiquette **For the reviewer:** + - Be specific. "This function is wrong" is less useful than "This function will return `None` when `x < 0`, which will crash the caller." + - Focus on the code, not the person. - Acknowledge good work. A review with only criticisms is demoralising. - Review in a timely manner. A PR waiting for review for a week blocks the author. **For the author:** + - Do not take feedback personally. The reviewer is improving the research output, not judging you. - Do not dismiss feedback without engaging with it. - Keep PRs small enough to review in one sitting (see Chapter 11). diff --git a/docs/student/13-merge-conflicts.md b/docs/student/13-merge-conflicts.md index 5551d0b..35029dd 100644 --- a/docs/student/13-merge-conflicts.md +++ b/docs/student/13-merge-conflicts.md @@ -64,6 +64,7 @@ with the correct merged result. ### Step 1: Understand the conflict Before editing, read both versions and understand: + - What did you change and why? - What did the other branch change and why? - Are the changes compatible? (Can both be kept?) @@ -78,6 +79,7 @@ VS Code detects conflict markers and shows a dedicated merge editor with three panels: "Current" (your branch), "Incoming" (theirs), and "Result". Click buttons to: + - **Accept Current Change** — keep your version - **Accept Incoming Change** — keep their version - **Accept Both Changes** — keep both (appended or combined) diff --git a/docs/student/16-faq.md b/docs/student/16-faq.md index 73ed18f..1bd03d2 100644 --- a/docs/student/16-faq.md +++ b/docs/student/16-faq.md @@ -258,6 +258,7 @@ git diff main feature/my-branch # compare branches 1. Rotate/revoke the credential immediately — treat it as compromised. 2. Contact the maintainer — the commit must be removed from history (this is non-trivial for a public or shared repository). + 3. Add the credentials file to `.gitignore` to prevent future accidents. Never commit credentials. Use environment variables or a `.env` file that is gitignored. diff --git a/docs/student/18-exercises.md b/docs/student/18-exercises.md index c8db79d..2195a06 100644 --- a/docs/student/18-exercises.md +++ b/docs/student/18-exercises.md @@ -48,6 +48,7 @@ git log --oneline -5 ``` Verify: + - The remote URL starts with `git@github.com:` - The log shows at least one commit @@ -61,6 +62,7 @@ cat README.md ``` Answer these questions in your notes: + 1. What files are at the top level? 2. Is there a `src/` directory? A `tests/` directory? 3. What is this code supposed to do (from the README)? @@ -82,6 +84,7 @@ git checkout -b docs/add-your-name Edit `CONTRIBUTORS.md` and add one line: ``` + - Your Name (Year) — Brief description of your research area ``` @@ -118,6 +121,7 @@ git log --oneline ### Exercise 2.3 — Interactive Staging In the file you created for Exercise 2.2, make two unrelated changes: + - Fix a typo in a comment - Add a second function @@ -169,6 +173,7 @@ git push -u origin feature/add-your-function ``` On GitHub, open a draft PR with: + - Title: `Add [function name] function` - Mark it as a draft (click the arrow next to "Create pull request") @@ -184,6 +189,7 @@ Ask a colleague (or the maintainer) to review your `docs/add-your-name` PR and leave at least one comment. Respond to the comment: + 1. Make the requested change (if any). 2. Commit and push. 3. Reply to the comment explaining what you did. @@ -215,14 +221,17 @@ Find a colleague who has an open PR. Review it: git log --oneline HEAD..origin/main ``` Confirm you are behind. + 3. Rebase: ```bash git rebase origin/main ``` + 4. Force-push: ```bash git push --force-with-lease ``` + 5. Verify the PR shows "no conflicts" on GitHub. --- @@ -243,6 +252,7 @@ Work with a colleague: git rebase origin/main # Conflict! ``` + 6. Resolve the conflict, stage the file, continue the rebase, and push. --- @@ -260,6 +270,7 @@ Work with a colleague: git reset --hard origin/main git checkout feature/recovered ``` + 5. Verify your commit is now only on `feature/recovered`. --- @@ -271,11 +282,13 @@ Work with a colleague: ```bash git stash ``` + 3. Switch to `main`, pull, switch back. 4. Pop the stash: ```bash git stash pop ``` + 5. Verify your changes are restored. --- @@ -285,6 +298,7 @@ Work with a colleague: ### Exercise 8.1 — Merge Your PR After your `docs/add-your-name` PR is approved: + - The maintainer will squash-merge it. - After the merge, clean up locally: ```bash @@ -292,6 +306,7 @@ After your `docs/add-your-name` PR is approved: git pull origin main git branch -d docs/add-your-name ``` + - Verify your name is now in `CONTRIBUTORS.md` on `main`. --- diff --git a/docs/templates/release-checklist.md b/docs/templates/release-checklist.md index 751ab43..4fe46dd 100644 --- a/docs/templates/release-checklist.md +++ b/docs/templates/release-checklist.md @@ -21,6 +21,7 @@ ```bash git tag -a vX.Y.Z -m "Release vX.Y.Z — brief description" ``` + - [ ] Tag pushed: `git push origin vX.Y.Z` - [ ] Tag verified on GitHub From aa962a7dffe0a1b9ac5565ae2bfb99782c5ff86d Mon Sep 17 00:00:00 2001 From: Yongcheng Wu Date: Sat, 11 Jul 2026 23:43:46 +0800 Subject: [PATCH 2/2] fix(index): update the group name --- docs/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index f84d23d..c48c614 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,6 @@ -# NNU-PP Research Software Handbook +# Meridex Research Software Handbook -Welcome to the official software engineering handbook for the NNU-PP research group. +Welcome to the official software engineering handbook for the Meridex research group. This handbook defines **how research software is developed, reviewed, and maintained in the group**. It covers the complete workflow from first setup to long-term repository maintenance.