diff --git a/.claude/worktrees/practical-babbage b/.claude/worktrees/practical-babbage new file mode 160000 index 0000000..77a4742 --- /dev/null +++ b/.claude/worktrees/practical-babbage @@ -0,0 +1 @@ +Subproject commit 77a4742269171974ee5919c0376a5e894e7f27a4 diff --git a/README.md b/README.md index 5009fc1..b6b4ff0 100644 --- a/README.md +++ b/README.md @@ -12,12 +12,12 @@ envision. Align with: -- [Principles](./docs/PRINCIPLES.md) - [Contributing Guidelines](./docs/CONTRIBUTING.md) - [Advocacy Guidelines](./docs/ADVOCACY.md) - [Code of Conduct](./docs/CODE_OF_CONDUCT.md) - [Leave Policy](./docs/LEAVE_POLICY.md) - [Compensation Guide](./docs/COMPENSATION.md) +- [Referral Program](./docs/REFERRAL.md) Subscribe to repository notifications to stay updated with frequent fixes and improvements. diff --git a/docs/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md index 1422477..03e0693 100644 --- a/docs/CODE_OF_CONDUCT.md +++ b/docs/CODE_OF_CONDUCT.md @@ -1,39 +1,55 @@ # Code of Conduct -1. Make sure you are aligned with our Core Values. -1. Ensure the quality of your work. It is a sign of poor ownership and lack of - confidence when you expect someone to deal with your incomplete work. -1. Assign yourself to the Problem you are solving so others are aware of it. -1. Use `@mention` only when the person truly needs to be notified or take action - — otherwise, use reactions (likes, thumbs up, etc.) for acknowledgment. -1. Leave daily updates on relevant tasks/problems to maintain visibility and - simplicity for the team. -1. Keep all communication task-focused: work topics, deliverables, questions, - status, decisions, outcomes only. No personal compliments/flattery, unrelated - hesitation/fear, or extra personal remarks. - ## Core Values -- **“Dream Big”** — it's important to set ambitious goals to challenge the +- **"Dream Big"** — it's important to set ambitious goals to challenge the status quo. Otherwise, it's not worth it. -- **“Do the Right Thing”** — if you do something “right” but it is the wrong +- **"Do the Right Thing"** — if you do something "right" but it is the wrong thing to do, your efforts will be in vain. -- **“Keep it Simple”** — simplicity is a significant key to success. The most +- **"Keep it Simple"** — simplicity is a significant key to success. The most complicated skill is to be simple. _In communication, this means keeping messages concise, clear, and work-centered. We value straightforward updates, feedback, and reactions over unnecessary elaboration or personal asides that can complicate understanding or slow progress._ -- **“Own it with Passion”** — we believe in taking ownership and responsibility - for our work. We encourage a mindset of accelerated learning as you “figure it - out yourself” and the drive to go beyond expectations. We are passionate about +- **"Own it with Passion"** — we believe in taking ownership and responsibility + for our work. We encourage a mindset of accelerated learning as you "figure it + out yourself" and the drive to go beyond expectations. We are passionate about what we do and understand that our team success is dependent on us. -- **“Be Open”** — expand your horizons by challenging your beliefs and embracing +- **"Be Open"** — expand your horizons by challenging your beliefs and embracing new knowledge, ideas, and opportunities. See things from the perspective of others, and you may uncover potential missteps and grow in your understanding. Open your mind to learn and grow, strengthening your self-belief. It's not failure that matters, but the ability to get back up after falling. -- **“Keep the Focus”** — to achieve our team goals, ask, “What is our biggest - obstacle?” and focus on the next actionable step. Continuously review our +- **"Keep the Focus"** — to achieve our team goals, ask, "What is our biggest + obstacle?" and focus on the next actionable step. Continuously review our goals to ensure that your actions are aligned. Identify areas of improvement constantly to streamline resources and enhance business efficacy. + +## Rules + +Make sure you are aligned with our Core Values and follow the rules below. + +### Ownership + +1. Ensure the quality of your work. It is a sign of poor ownership and lack of + confidence when you expect someone to deal with your incomplete work. +1. Assign yourself to the Goal or Problem you are working on so others are aware + of it. + +### Communication + +1. Use `@mention` only when the person truly needs to be notified or take action + — otherwise, use reactions (likes, thumbs up, etc.) for acknowledgment. +1. Leave daily updates on relevant tasks/problems to maintain visibility and + simplicity for the team. +1. Keep all communication task-focused: work topics, deliverables, questions, + status, decisions, outcomes only. No personal compliments/flattery, unrelated + hesitation/fear, or extra personal remarks. +1. Work async. Keep meetings to a minimum — one team sync per week is the norm. + Do not schedule meetings unless truly necessary. + +### Availability + +1. Be online during core hours: **2–6 PM HKT**. The rest of your schedule is + flexible. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index ac1aa20..4b9c114 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -4,12 +4,25 @@ Thank you for your interest in contributing to our project! Your accepted contributions will be reflected in our repositories and related websites. Please read our [Code of Conduct](./CODE_OF_CONDUCT.md) to keep our community -approachable and respectful. -If you are a permanent contributor, read our [Principles](./PRINCIPLES.md). +approachable and respectful. > [!TIP] -> You can use [Wizard Browser Extension][1] to simplify some of the workflows -> described in these Guidelines. +> You can use [Wizard GitHub App][2] and [Wizard Browser Extension][1] to +> simplify some of the workflows described in these Guidelines. + +## Table of Contents + +- [Getting started](#getting-started) + - [Goal](#goal) + - [Problem](#problem) + - [Solution](#solution) +- [Communication Guidelines](#communication-guidelines) +- [PR Requirements](#pr-requirements) + - [Commit Signature Verification](#commit-signature-verification) + - [Scoping](#scoping) + - [Naming](#naming) + - [PR Lifecycle](#pr-lifecycle) + - [Review Process](#review-process) ## Getting started @@ -29,8 +42,14 @@ There are three core contribution pillars: Understanding the Goal and its business context is crucial for successful contribution. +To find a Goal to work on, browse GitHub Issues in the relevant repository and +filter for issues with the `Goal:` prefix. Prioritize issues based on their +impact and urgency. If you are unsure which Goal to choose, please consult +your lead. Pick one that matches your skills, then proceed with the steps below. + As soon as you get involved, you must: +1. assign yourself to the Goal issue. 1. analyze specifications (the Specs), 1. assess progress and outstanding Problems and 1. provide an estimated time of achieving (ETA) the Goal. @@ -43,61 +62,38 @@ permissions) and an ETA. > following naming pattern: `Goal: [statement]`. > Goals are created and managed by Partner level contributors. -#### Communication within Goal issues - -To maintain clarity and efficiency, discussions should be directed to the -appropriate channels: - -- **Use the Spec document** for clarifications about the Goal, its scope, or - business context. -- **Use Problem issues** for tracking obstacles that prevent achieving the Goal. -- **Goal issues should remain clean**, primarily linking Specs, tracking - Problems, and monitoring progress. - -If you identify a potential new problem but are unsure whether it is planned: - -1. First, check if there is an existing Problem issue related to your concern. -1. If there isn't, ask for clarification in the Spec document. -1. If necessary, create a new Problem issue and discuss it there. - -Avoid extended discussions in Goal issues. Instead, move conversations to the -relevant Spec document or Problem issue. - ### Problem -Once the Goal is clear, you must identify what stops you from achieving it. -Anything that is stopping you - is a “Problem”. A typical question to ask is: -"Why is this Goal not achieved and what is the Problem?". - -Sometimes, a Goal already has a few identified problems, but not always. +Once a Goal is clear, you must identify what prevents its achievement. +Anything that acts as a barrier is considered a "Problem." Ask yourself: +"Why is this Goal not achieved, and what specifically is the problem?" > [!NOTE] -> Once a Problem is identified, we report it as a -> [GitHub Issue](https://docs.github.com/en/issues) with the following naming -> pattern: `Problem: [statement]`. We’re counting on our contributors to -> identify problems. Keep a Problem name short (under 65 chars) and crystal -> clear. +> Report each Problem as a [GitHub Issue](https://docs.github.com/en/issues) +> using the naming pattern: `Problem: [statement]`. Keep the name short +> (under 65 characters) and crystal clear. -Make sure each Problem issue is interlinked with it's Goal issue: +The statement must be a **job story** — describe what a specific user **cannot +do** or what is broken for them. Ask: _"What can [user] not do because of this +problem?"_ -- add a Problem issue link into the Goal description -- add a Goal issue link to the Problem description +| **Good** ✅ | **Bad** ❌ | **Why?** | +| ---------------------------------------------- | -------------------------------------------- | ------------------------------ | +| `operators can't view their account balance` | `operators don't have their account balance` | Describes inability, not state | +| `users can't submit a form without refreshing` | `form submission issue` | Vague, no actor or action | +| `admins can't export reports as CSV` | `CSV export missing` | No subject, not a job story | -It's essential to maintain clear links between Goals and related Problem issues. -This helps everyone stay informed and team members can easily track progress and -understand the context. +Ensure each Problem issue is properly interlinked with its parent Goal issue: -> [!IMPORTANT] -> Do not post Problem status updates or notifications back into the Goal issue. -> The link between them is sufficient — keep all updates within the Problem -> issue itself. +- Add the Problem issue link to the Goal description. +- Add the Goal issue link to the Problem description. ### Solution The third pillar of successful contribution is the Solution. Different problems may require different sets of skills. -Whether it’s code, design, or marketing material, we expect a lean and clean +Whether it's code, design, or marketing material, we expect a lean and clean solution from the contributor. > [!NOTE] @@ -105,21 +101,38 @@ solution from the contributor. > [Pull Request (PR)](https://docs.github.com/en/pull-requests) in compliance > with [PR Requirements](#pr-requirements). +## Communication Guidelines + +### Discussion channels + +Direct discussions to the appropriate channel at all times: + +- **Spec document** — clarifications about Goal scope or business context +- **Problem issues** — tracking obstacles that prevent achieving the Goal +- **Goal issues** — linking Specs, tracking Problems, and monitoring progress + only + > [!IMPORTANT] -> Do not repost PR notifications or progress updates in the Goal issue. The PR -> is linked to the Problem, which is linked to the Goal — that chain is -> sufficient. Duplicate comments add noise. +> Do not post Problem status updates, PR notifications, or progress updates in +> Goal issues. The Goal → Problem → PR chain makes these redundant and adds +> noise. + +If you identify a potential new problem but are unsure whether it is planned: + +1. Check if there is an existing Problem issue related to your concern. +1. If not, ask for clarification in the Spec document. +1. If necessary, create a new Problem issue and discuss it there. -### Referencing +If someone's action is required to unblock progress, assign them to the Goal +issue so the dependency is visible. -When referencing issues or pull requests in any GitHub discussion, use a list -item format to enable automatic title rendering and improve readability. This -ensures that GitHub automatically expands the reference to show the issue/PR -title. +### Referencing issues and PRs -#### Correct Format +When referencing issues or pull requests, use a list item format to enable +automatic title rendering and improve readability. This ensures that GitHub +automatically expands the reference to show the issue/PR title. -Use a list item to reference issues or PRs: +**Correct** — use a list item: ```md See these related items: @@ -130,47 +143,54 @@ See these related items: - #12 ``` -#### Incorrect Formats - -Avoid simply pasting the URL inline. +**Incorrect** — avoid inline pasting: ```md Check this out: Related: See for details ``` -> [!NOTE] -> The list format improves readability and helps contributors quickly understand -> the context by showing the referenced issue/PR titles automatically. - ## PR Requirements -All PRs, whether for source code, design, or copy changes, must comply with our -PR Requirements. +All PRs, whether for source code, design, or copy changes, must comply with the +following requirements. > [!WARNING] -> PRs that do not correspond to the following criteria are usually rejected. +> PRs that do not correspond to the following criteria will be rejected. + +Before marking your PR as ready for review, confirm: + +- [ ] Commits are signed +- [ ] PR scope fits within 3–4 hours of work +- [ ] All CI checks pass +- [ ] PR is linked to a Problem issue +- [ ] At least one reviewer is assigned +- [ ] Time is reported +- [ ] PR title follows `type(scope): action` naming convention +- [ ] Preview link is included (if applicable) +- [ ] README is updated to reflect any functional changes -## Commit Signature Verification +### Commit Signature Verification For the security and integrity of our project, we require all contributors to sign their commits. For detailed instructions on why and how to sign your commits refer to [GitHub's documentation on commit signature verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification). -> [!Note] We recommend signing commits using an +> [!NOTE] +> We recommend signing commits using an > [SSH key](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification#ssh-commit-signature-verification). > Ensure your Git version supports SSH signature verification (Git 2.34 or > later). -## Scoping +### Scoping -> [!NOTE] +> [!TIP] > Here's a [good resource](https://youtu.be/bmSAYlu0NcY?si=2lLQeY1PGCY9tcvX) on software design philosophy. When planning the scope of work, make sure you [keep PRs small](https://artsy.github.io/blog/2021/03/09/strategies-for-small-focused-pull-requests/). -You must be able to complete your PR within 3-4 hours. +You must be able to complete your PR within 3–4 hours. If the solution requires more time, then decompose it into smaller independent PRs. In case your smaller PRs can't be used on production, use feature flags. @@ -178,45 +198,51 @@ We usually reject and close PRs which do not have activity for the last 24 hours, unless there is a clear comment explaining the reason why that PR is stalled. -## CI Checks +When introducing functional changes, cross-check the README and update it in +the same PR. If your change affects anything documented there — setup steps, +environment requirements, file references — the README must stay in sync. -To maintain the quality and integrity of our project, all PRs must successfully -pass the required Continuous Integration (CI) checks before being marked as -"ready to review." PRs with failing CI checks will be rejected. +### Naming -The required checks are as follows: +> [!NOTE] +> We use PR titles to communicate changes to all stakeholders, including +> non-technical users. -```text -- The pr-time-tracker verifies that the time spent on the PR has been properly logged. -- The pr-time-tracker for bugs ensures that bug-related time tracking is correctly linked to the corresponding commit and bug author. -- The code-rabbit validates that the code meets quality standards and passes all automated checks. -``` +PR names must be: -> [!NOTE] -> Contributors need to resolve all CI issues before assigning reviewers or -> requesting a review. Any PR with unresolved CI checks should remain in "draft" -> status until all issues are fixed. +1. **User-focused**: Describe what users gain, not technical implementation +1. **Follow [Conventional Commits](https://www.conventionalcommits.org)** +1. **Clear & simple** (present tense, action-oriented) -## Drafting +| **Good Examples** ✅ | **Bad Examples** ❌ | **Why?** | +| ---------------------- | ------------------------------ | ------------------ | +| `feat(ui): play music` | `Create player` | Missing scope/type | +| `fix(sdk): mute sound` | `Fix: add file to mute sound` | Technical details | +| `test(api): open door` | `Feat: modified door function` | Vague, past tense | -When starting to work on a Problem, you must: +A feature isn't a button, toggle, or handler — it's +**what the user gains from it**. Ask _"What will users be able to do?"_ not +_"What am I building?"_ -1. Open a - [draft PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests) - right away. Do not mark PR as "ready to review" unless you are confident it - is ready. -1. [Link opened PR](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) - to the corresponding Problem (issue). -1. Before marking your PR as ready for review, assign **at least one reviewer** - (team or individual). Do not merge without approved review. +1. **Replace UI labels with actions**: Wrong: "Add dropdown for filters" → + Correct: "Filter search results by category" +1. **Describe outcomes, not components**: Wrong: "Fix API error handling" → + Correct: "Gracefully recover from connection errors" +1. **Use user action verbs**: _View, Play, Customize, Save_, etc. -### Design PRs +#### Before Submitting, Ask -Initiate a PR with a note in the DESIGN.md file detailing the addressed design -aspects. Design PRs use `docs(ui)` as the "type" and "scope" of its name. i.e.: -`docs(ui): design table component` +1. Does it use `type(scope [Optional]): action` format? +1. Could a non-technical user understand the benefit? +1. Is it in the present tense? +1. Does it focus on user capability (not code)? -Structure the design file with the following markup: +#### Design PRs + +Design PRs use `docs(ui)` as the type and scope. e.g.: `docs(ui): design table component` + +Initiate a PR with a note in the DESIGN.md file detailing the addressed design +aspects. Structure the design file with the following markup: ```text ## Feature @@ -226,15 +252,13 @@ Structure the design file with the following markup: - [[state]](https://figma.com/your-design-file-url) ``` -#### Key +**Key:** -- **`/...`** - Represents a page. -- **`{...}`** - Represents a dynamic parameter within a URL. -- **`(...)`** - Used for grouping related features or components. -- **`[...]`** - Indicates a specific state of the page or component, such as a - popup or modal state. -- Indentation in the list represents the tree structure or hierarchy, showing - how components or features are nested or related. +- **`/...`** — a page +- **`{...}`** — a dynamic URL parameter +- **`(...)`** — a grouping of related features or components +- **`[...]`** — a specific state (e.g. popup or modal) +- Indentation represents nesting hierarchy Example: @@ -247,97 +271,61 @@ Example: - [[Bid Popup]](https://figma.com/your-design-file-url) ``` -If there isn't an existing DESIGN.md file: - -1. Create a new file named DESIGN.md. -1. Link it from README.md. - -## Naming - -> [!NOTE] -> We use PR titles to communicate changes to all stakeholders, including -> non-technical users. - -PR names must be: - -1. **User-focused**: Describe what users gain, not technical implementation -1. **Follow [Conventional Commits](https://www.conventionalcommits.org)** -1. **Clear & simple** (present tense, action-oriented) - -### Example Comparison - -| **Good Examples** ✅ | **Bad Examples** ❌ | **Why?** | -| ---------------------- | ------------------------------ | ------------------ | -| `feat(ui): play music` | `Create player` | Missing scope/type | -| `fix(sdk): mute sound` | `Fix: add file to mute sound` | Technical details | -| `test(api): open door` | `Feat: modified door function` | Vague, past tense | - ---- - -### Key Principles - -#### What to Focus On +If there isn't an existing DESIGN.md file, create one and link it from README.md. + +### PR Lifecycle + +Follow these steps in order from start to submission: + +1. **Open a [draft + PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests)** + right away when you start working on a Problem. +1. **[Link the + PR](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword)** + to the corresponding Problem issue using a closing keyword. +1. **Assign yourself** so it is clear who is working on it. +1. **Resolve all CI checks** — PRs with failing checks will be rejected. +1. **Report your time** spent across all stages: planning (40%), implementation, + and QA (20–30%). Open the PR early so time tracking starts from the + beginning, including investigation. +1. **Assign at least one reviewer** (team or individual). +1. **Include a preview link** — if your changes are visually verifiable (UI, + design, or any deployable artifact), add a link to the deployed preview or + prototype in the PR description. +1. **Mark as ready for review** only once all steps above are complete. -A feature isn’t a button, toggle, or handler—it’s -**what the user gains from it**. Ask: - -- ❌ _"What am I building?"_ → Leads to technical labels. -- ✅ _"What will users be able to do?"_ → Leads to clear value. - -#### Why It Matters - -- **Clarity**: Engineers, PMs, and stakeholders instantly understand the impact. -- **Consistency**: Aligns with product-facing language (release notes, docs). -- **User-Centricity**: Work is driven by user needs, not just code changes. - -#### How to Apply It - -1. **Replace UI labels with actions**: Wrong: "Add dropdown for filters" → - Correct:"Filter search results by category" -1. **Describe outcomes, not components**: Wrong: "Fix API error handling" → - Correct:"Gracefully recover from connection errors" -1. **Use user action verbs**: _View, Play, Customize, Save_, etc. - -### Before Submitting, Ask - -1. Does it use `type(scope [Optional]): action` format? -1. Could a non-technical user understand the benefit? -1. Is it in the present tense? -1. Does it focus on user capability (not code)? - -## Requesting Review +> [!WARNING] +> Do not merge without an approved review. -Once your PR is ready, assign reviewers and mark it as "ready to review." But -before that, report the time you have spent on it. +### Review Process -> [!NOTE] -> When contributing, it's essential to report time accurately, including all -> stages of development (planning, implementation, QA). We encourage opening a -> PR at the start of your work, even during the planning or investigation phase. -> Programming and designing isn't just about writing code or creating designs; -> it also involves planning (40%) and QA (20-30%). +#### Giving a Review -### Reviewing PRs +If a PR is not ready to merge, you **must** use **Request Changes** (reject). +Do not leave a plain comment when rejection is warranted — comments do not +block merging, are not recorded as rejections, and prevent the author from +re-requesting a review. -Use **Request Changes** (reject) only for objective problems: +Use **Request Changes** (reject) for objective problems: - PR doesn't solve the stated problem. - A bug is introduced. - Code style is inconsistent. - Required guidelines are violated. -Use **Comment** for optional improvements or suggestions. +Use **Comment** for optional improvements or suggestions that should not block +the PR. -### Scout approach +#### Scout Approach If you ever have free time, be proactive and apply the scout approach: own the job, look for PRs that still need reviewers, and offer timely feedback so work keeps moving. -### Code Quality and Reviews +#### Code Quality Aim for solutions that work correctly 99.9% of the time. Be independent and -thorough in your QA - reviewers are not QA team members but are there for a +thorough in your QA — reviewers are not QA team members but are there for a final safety check. We expect contributors to deliver bug-free software, understanding that perfection is an ideal. Stand firm in your solutions and avoid unnecessary revisions based on subjective feedback. @@ -345,3 +333,4 @@ avoid unnecessary revisions based on subjective feedback. --- [1]: https://chromewebstore.google.com/detail/wizard-browser-extension/gibcadmedmabfnfbolimcndljcopbhep +[2]: https://github.com/apps/holdex diff --git a/docs/PRINCIPLES.md b/docs/PRINCIPLES.md deleted file mode 100644 index 9d3a067..0000000 --- a/docs/PRINCIPLES.md +++ /dev/null @@ -1,45 +0,0 @@ -# Our Principles - -**We build great things together—fast, smart, and with full ownership.** - -## The 6 Rules We Live By - -1. **Start with the Goal** - Keep the big picture. Break it into clear problems. Solve one at a time. - -1. **Own It Like a Founder** - No one assigns tasks. You spot problems, claim them, and deliver results. - -1. **Ship Daily, Small & Often** - No task >4 hours. Finish, push, move on. Momentum beats perfection. - -1. **Respect Time—Yours & Others** - One team sync/week. Work async. No meetings unless needed. - -1. **Wear Many Hats** - Code, design, test, write, explore. We grow by doing. - -1. **Figure It Out** - Research. Read. Ask. Learn fast. No waiting for instructions. - ---- - -## Do This | Not That - -| ✅ **Do** | ❌ **Don’t** | -| ------------------------- | ----------------------- | -| Solve what moves the goal | Work on low-value tasks | -| Own it end-to-end | Pass the buck | -| Test your work | Expect others to QA | -| Leave clear updates | Vanish without trace | - ---- - -## ⏰ Core Hours - -**2–6 PM HKT** — Be online. Rest is flexible. - ---- - -**Be bold. Be fast. Be kind.** -That’s how we win. diff --git a/docs/REFERRAL.md b/docs/REFERRAL.md new file mode 100644 index 0000000..9256a80 --- /dev/null +++ b/docs/REFERRAL.md @@ -0,0 +1,19 @@ +# Referral Program + +Referrals are accepted for two types: + +- **Contributors** — someone you refer who joins and stays active for more than + 3 months. +- **Business** — a client or partner you refer who engages with us. + +In both cases, for a referral to be registered, the applicant or prospect must +name you as the referral at the time of their application or first contact. +Referrals claimed after the fact will not be counted. + +Once the eligibility conditions are met, reach out to your lead to claim the +reward. + +> [!IMPORTANT] +> This referral program applies unless there is a separate commercial +> engagement between Holdex and the contributor, in which case referral terms +> are governed by that agreement instead.