docs: view scope as optional

[angelicawill]

resolves #66

Summary by CodeRabbit

• Documentation
  • Refined contributor guidelines: clarified PR naming, converted negative markers to positive, and harmonized emphasis/tense across guidance
  • Improved example tables (Good/Bad, Why?) and tightened layout for readability
  • Updated "Before Submitting" checklist to present-tense phrasing
  • New review procedures: assign reviewers before review and report time spent (planning, implementation, QA)
  • Strengthened Scout approach and Code Quality & Reviews expectations for timely, independent feedback

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Editorial and formatting updates to docs/CONTRIBUTING.md: PR naming guidance reformatted (clarifies optional scope), example tables and emphasis styling adjusted, present-tense phrasing standardized, and "Requesting Review" expanded to require assigning reviewers and recording time spent (planning, implementation, QA).

Changes

Cohort / File(s)	Summary
CONTRIBUTING doc updates docs/CONTRIBUTING.md	Reformats PR naming guidance and examples, clarifies that scope is optional in type[optional scope]: description, adjusts emphasis/tense across examples and key principles, and expands "Requesting Review" to require reviewer assignment and time-spent reporting (planning, implementation, QA).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Documentation-only edits, primarily formatting and wording changes.
• Review focus:
  • Verify PR-naming examples correctly show optional scope.
  • Confirm "Requesting Review" phrasing and time-reporting requirements are clear and consistent.
  • Check example tables for alignment and rendering.

Possibly related PRs

• ci: run Markdown linter #68 — Also edits docs/CONTRIBUTING.md with editorial/formatting updates.
• docs: view scout approach in contribution guidelines #65 — Overlaps on strengthening the "Scout approach" and reviewer guidance.
• docs: clarify pull request naming #58 — Related changes to PR-naming examples and the submission checklist.

Suggested reviewers

• zolotokrylin
• markholdex

Pre-merge checks and finishing touches

❌ Failed checks (1 warning, 2 inconclusive)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The raw summary indicates changes beyond the stated objective: time-tracking requirements, Scout approach guidance, and Code Quality expectations appear unrelated to clarifying optional scope.	Review and either justify all changes in CONTRIBUTING.md against issue #66 requirements or move unrelated documentation updates to separate PRs.
Title check	❓ Inconclusive	The title 'docs: view scope as optional' is vague and doesn't clearly reflect the main changes to CONTRIBUTING.md beyond scope formatting.	Consider a more descriptive title like 'docs: clarify PR scope is optional' or 'docs: update CONTRIBUTING with optional scope guidance' to better reflect the actual changeset.
Linked Issues check	❓ Inconclusive	The PR objectives specify extending guidelines to clarify scope is optional, but the raw summary shows extensive formatting and content changes beyond scope clarification.	Clarify whether all documented changes to CONTRIBUTING.md (formatting, Key Principles, time-tracking, Scout approach) align with resolving issue #66 or represent scope creep.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

.github/CONTRIBUTING.md (1)

239-239: Clarify the optional scope notation to follow Conventional Commits convention.

The current notation type(scope [Optional]): action is ambiguous—it's unclear whether the literal string [Optional] should appear in commit messages. The document references Conventional Commits (line 207), which uses square brackets around the optional element itself.

Apply this diff to align with standard convention:

-1. Does it use `type(scope [Optional]): action` format?
+1. Does it use `type([scope]): action` format?

Then, optionally add clarifying text after the checklist item (e.g., "where scope is optional") if you'd like to be extra explicit.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d4b928b and 0bd6a9b.

📒 Files selected for processing (1)

• .github/CONTRIBUTING.md (1 hunks)

[holdex]

Time Submission Status

Member	Status	Time	Action	Last Update
angelicawill	✅ Submitted	30min	Update time	Dec 2, 2025, 1:06 PM
zolotokrylin	✅ Submitted	15min	Update time	Dec 2, 2025, 1:07 PM

[angelicawill]

Please review @zolotokrylin thank you!

[zolotokrylin]

@angelicawill, could you please resolve this conflict? Thank you.

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 0bd6a9b and 52daedb.

📒 Files selected for processing (1)

• docs/CONTRIBUTING.md (2 hunks)

🧰 Additional context used

🪛 GitHub Check: lint

docs/CONTRIBUTING.md

[warning] 283-283: MD029
Ordered list item number 4 does not match configured style 'one' (expected 1)

---

[warning] 282-282: MD029
Ordered list item number 3 does not match configured style 'one' (expected 1)

---

[warning] 281-281: MD029
Ordered list item number 2 does not match configured style 'one' (expected 1)

🔇 Additional comments (3)

docs/CONTRIBUTING.md (3)

280-280: ✅ Scope optionality clearly documented.

The change explicitly notes type(scope [Optional]): action format, directly addressing issue #66. This clarifies that scope is optional and should help reviewers avoid rejecting PRs solely for omitting scope.

---

285-291: New procedural guidance on time tracking is helpful.

The "Requesting Review" section (lines 285–291) adds clear guidance about reporting time spent on PRs and contextualizes development work to include planning and QA phases. This reinforces accountability and realistic estimation.

---

239-276: Overall naming guidance improvements are clear and user-focused.

The restructured PR naming requirements (user-focused, Conventional Commits, clear & simple), example comparison table, and emphasis on user capability over technical details strengthen the guidelines. The formatting and emphasis changes improve readability and hierarchy.

[angelicawill]

@zolotokrylin resolved

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

docs/CONTRIBUTING.md (1)

280-283: Clarify the optional scope notation for alignment with Conventional Commits standard.

The change from type(scope): action to type(scope [Optional]): action directly addresses issue #66 by documenting that scope is optional. However, the Conventional Commits specification uses the notation <type>[optional scope]: <description>, which more clearly indicates optionality using square brackets.

Consider revising to one of these alternatives for better alignment with the standard:

• Option 1 (Matches Conventional Commits standard): Change line 280 to: type[(scope)]: action and add clarifying text: "where (scope) is optional"
• Option 2 (Keep current, add explanation): Retain the current format but immediately add: "where the scope in parentheses is optional"

This ensures contributors recognize the standard notation when they reference other Conventional Commits documentation.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 52daedb and 32680f6.

📒 Files selected for processing (1)

• docs/CONTRIBUTING.md (2 hunks)

🔇 Additional comments (5)

docs/CONTRIBUTING.md (5)

239-241: Approve PR naming requirements section.

Clear presentation of three core requirements for PR names. This section effectively communicates the standards to contributors.

---

245-249: Example comparison table is well-structured.

The Good/Bad examples effectively illustrate the PR naming conventions. The "Why?" column provides helpful context for why certain formats are preferred.

---

257-267: Key Principles section strengthens user-focus messaging.

The emphasis on "what users gain" over technical implementation is well-articulated. The use of ❌/✅ indicators provides visual clarity.

---

271-276: How to Apply It examples are practical and instructive.

Concrete examples of wrong vs. correct approaches, with emphasis on user action verbs, make the guidance actionable for contributors.

---

287-291: Requesting Review section effectively communicates time-tracking expectations.

The expanded guidance on reporting time across planning, implementation, and QA phases is clear and helpful. The note explaining that "Programming isn't just about writing code" provides good context for why full-stage time tracking is important.