From 81c8ddc08d058947afa00d508eaeada9fc0ae009 Mon Sep 17 00:00:00 2001 From: Joe Ben <70404172+joebenclark@users.noreply.github.com> Date: Fri, 19 Jun 2026 10:41:27 -0500 Subject: [PATCH 1/3] Add files via upload --- CONTRIBUTING.md | 120 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 120 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..afb8fd8 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,120 @@ +# Contributing to cdisc-org + +Thank you for contributing to CDISC's open source work. This guide explains how we estimate and track work across all repositories in the `cdisc-org` organization so that progress can be reported consistently to CDISC leadership and the broader community. + +--- + +## Table of Contents + +1. [Work Estimation Overview](#work-estimation-overview) +2. [T-Shirt Size Scale](#t-shirt-size-scale) +3. [How Estimation Works: Planning Poker](#how-estimation-works-planning-poker) +4. [Submitting Issues](#submitting-issues) +5. [GitHub Project Workflow](#github-project-workflow) +6. [For Outside Collaborators](#for-outside-collaborators) +7. [How This Feeds Leadership Reporting](#how-this-feeds-leadership-reporting) + +--- + +## Work Estimation Overview + +We use **T-shirt sizing** to estimate the effort, complexity, and uncertainty of each issue. T-shirt sizes are a relative measure — not hours or days — which keeps estimates consistent across team members, time zones, and varying levels of technical background. + +The core principle: every issue is estimated *relative to other issues*, not in absolute time. A Medium issue is roughly twice as complex as a Small one. Over time, the distribution of sizes across a milestone gives leadership a reliable picture of scope and progress. + +This approach is used by the CDISC Data Science and COSA teams and is designed to be accessible to both internal contributors and outside collaborators. + +--- + +## T-Shirt Size Scale + +| Size | Meaning | Rough Guidance | Example | +|------|---------|----------------|---------| +| **XS** | Trivial | A few hours | Update a config value, fix a typo in documentation | +| **S** | Small | Half a day to a day | Add a field to an existing schema, update a README section | +| **M** | Medium | A few days | Implement a small new feature with clear requirements | +| **L** | Large | About a week | Refactor a module, new API endpoint, multi-repo coordination | +| **XL** | Extra Large | Multi-week | Major architectural change or new integration — consider breaking down | + +> **Rule of thumb:** XL issues should be broken into smaller, independently deliverable issues before work begins whenever possible. + +--- + +## How Estimation Works: Planning Poker + +The CDISC core team uses **Planning Poker** to arrive at estimates collaboratively. Here is how it works: + +1. **Issue author** presents the issue — reads the title, description, and acceptance criteria aloud (or in a shared call). +2. **Each estimator** independently selects a size without revealing it. +3. **All sizes are revealed simultaneously** — this prevents anchoring bias where early opinions influence others. +4. **If everyone agrees**, the size is recorded and the team moves on. +5. **If there is disagreement**, the highest and lowest estimators briefly explain their reasoning. This conversation surfaces hidden complexity or missing context that improves the whole team's understanding. +6. **Re-vote** until the team converges. The goal is shared understanding, not a perfect answer. + +Planning Poker sessions are held at the start of each sprint. New issues submitted between sprints are estimated in the following session unless they are urgent. + +--- + +## Submitting Issues + +When opening a new issue in any `cdisc-org` repository: + +- **Do not assign a size yourself** — leave the "T-Shirt Size" field blank. The core team will estimate it during the next Planning Poker session. +- **Write clear acceptance criteria** — the single biggest driver of estimation accuracy is understanding *what done looks like*. Use the format: + ``` + Given [context], when [action], then [expected result]. + ``` +- **Link related issues** — if your issue depends on or is blocked by another, note it in the description. +- **Use the issue template** if one exists in the repository. + +If you have a rough sense of complexity and want to share it, add a comment with your thinking — the team will consider it during estimation. Do not set the T-Shirt Size field directly. + +--- + +## GitHub Project Workflow + +All issues across `cdisc-org` repositories are tracked in the **CDISC IT & Open Source Org-Level Project**. Issues move through the following workflow: + +| Status | Meaning | +|--------|---------| +| **Backlog** | Issue is open but not yet estimated or scheduled | +| **Ready** | Estimated and ready to be pulled into a sprint | +| **In Progress** | Actively being worked on in the current sprint | +| **In Review** | Pull request open, awaiting review | +| **Done** | Merged and closed | + +**Custom fields on every issue:** + +- **T-Shirt Size** — XS / S / M / L / XL, assigned after Planning Poker +- **Iteration** — The sprint this issue is assigned to (2-week cycles) +- **Milestone** — The release or roadmap milestone this issue contributes to + +--- + +## For Outside Collaborators + +Welcome — we are glad to have you. Here is what you need to know: + +- **Open issues freely.** You do not need to estimate your own issues. The CDISC core team handles estimation. +- **Pull requests are welcome** for issues labeled `good first issue` or `help wanted`. +- **If you are picking up an unassigned issue**, leave a comment so the team can confirm it is ready and assign it to you. +- **Milestone dates are set by the core team.** If you are working toward a milestone, check with the issue author or a maintainer to confirm the target date is still accurate. +- **Questions?** Open a discussion in the relevant repository or reach out via the COSA community channels. + +All contributions, regardless of source, are tracked in the same GitHub Project so that reporting to CDISC leadership is unified. + +--- + +## How This Feeds Leadership Reporting + +T-shirt sizes and iterations feed two key views used for leadership reporting: + +**Size distribution** — Shows the breakdown of XS / S / M / L / XL work remaining in a milestone. This gives leadership an at-a-glance read on scope: a milestone heavy in L and XL issues is a different conversation than one that is mostly S and M. + +**Milestone roadmap** — Each repository's milestones have target end dates. The org-level project roadmap view shows all active milestones across repos on a timeline, giving leadership a single view of what is in flight and when it is expected to land. + +These views are available in the GitHub Project's **Insights** tab and are refreshed automatically as issues are updated. + +--- + +*This document is maintained by the CDISC IT team. For questions about the estimation process, contact [jbclark@cdisc.org](mailto:jbclark@cdisc.org).* From 017e7296bf116f06e8e2f2cf3e7cbb260d722a01 Mon Sep 17 00:00:00 2001 From: Joe Ben <70404172+joebenclark@users.noreply.github.com> Date: Fri, 19 Jun 2026 14:08:28 -0500 Subject: [PATCH 2/3] Julie states: Joe Ben, I reviewed this and it looks fine to me. However, the Poker Planning section seems like a lot of overhead to have voting on every issue. To me this takes too much time/effort. I am fine with just the issue owner estimating the effort, rather than having the core team vote on size. --- CONTRIBUTING.md | 32 ++++++++------------------------ 1 file changed, 8 insertions(+), 24 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index afb8fd8..355776f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,11 +8,10 @@ Thank you for contributing to CDISC's open source work. This guide explains how 1. [Work Estimation Overview](#work-estimation-overview) 2. [T-Shirt Size Scale](#t-shirt-size-scale) -3. [How Estimation Works: Planning Poker](#how-estimation-works-planning-poker) -4. [Submitting Issues](#submitting-issues) -5. [GitHub Project Workflow](#github-project-workflow) -6. [For Outside Collaborators](#for-outside-collaborators) -7. [How This Feeds Leadership Reporting](#how-this-feeds-leadership-reporting) +3. [Submitting Issues](#submitting-issues) +4. [GitHub Project Workflow](#github-project-workflow) +5. [For Outside Collaborators](#for-outside-collaborators) +6. [How This Feeds Leadership Reporting](#how-this-feeds-leadership-reporting) --- @@ -40,26 +39,11 @@ This approach is used by the CDISC Data Science and COSA teams and is designed t --- -## How Estimation Works: Planning Poker - -The CDISC core team uses **Planning Poker** to arrive at estimates collaboratively. Here is how it works: - -1. **Issue author** presents the issue — reads the title, description, and acceptance criteria aloud (or in a shared call). -2. **Each estimator** independently selects a size without revealing it. -3. **All sizes are revealed simultaneously** — this prevents anchoring bias where early opinions influence others. -4. **If everyone agrees**, the size is recorded and the team moves on. -5. **If there is disagreement**, the highest and lowest estimators briefly explain their reasoning. This conversation surfaces hidden complexity or missing context that improves the whole team's understanding. -6. **Re-vote** until the team converges. The goal is shared understanding, not a perfect answer. - -Planning Poker sessions are held at the start of each sprint. New issues submitted between sprints are estimated in the following session unless they are urgent. - ---- - ## Submitting Issues When opening a new issue in any `cdisc-org` repository: -- **Do not assign a size yourself** — leave the "T-Shirt Size" field blank. The core team will estimate it during the next Planning Poker session. +- **Set your own T-Shirt Size** — as the issue owner, you are responsible for selecting the size that best reflects the effort and complexity of your issue. Use the scale above as your guide. - **Write clear acceptance criteria** — the single biggest driver of estimation accuracy is understanding *what done looks like*. Use the format: ``` Given [context], when [action], then [expected result]. @@ -67,7 +51,7 @@ When opening a new issue in any `cdisc-org` repository: - **Link related issues** — if your issue depends on or is blocked by another, note it in the description. - **Use the issue template** if one exists in the repository. -If you have a rough sense of complexity and want to share it, add a comment with your thinking — the team will consider it during estimation. Do not set the T-Shirt Size field directly. +If you are unsure of the right size, pick your best estimate and add a comment explaining your reasoning — a maintainer may adjust it if needed. --- @@ -85,7 +69,7 @@ All issues across `cdisc-org` repositories are tracked in the **CDISC IT & Open **Custom fields on every issue:** -- **T-Shirt Size** — XS / S / M / L / XL, assigned after Planning Poker +- **T-Shirt Size** — XS / S / M / L / XL, set by the issue owner when the issue is created - **Iteration** — The sprint this issue is assigned to (2-week cycles) - **Milestone** — The release or roadmap milestone this issue contributes to @@ -95,7 +79,7 @@ All issues across `cdisc-org` repositories are tracked in the **CDISC IT & Open Welcome — we are glad to have you. Here is what you need to know: -- **Open issues freely.** You do not need to estimate your own issues. The CDISC core team handles estimation. +- **Open issues freely.** Set the T-Shirt Size field to your best estimate of the effort involved — use the scale in this guide. - **Pull requests are welcome** for issues labeled `good first issue` or `help wanted`. - **If you are picking up an unassigned issue**, leave a comment so the team can confirm it is ready and assign it to you. - **Milestone dates are set by the core team.** If you are working toward a milestone, check with the issue author or a maintainer to confirm the target date is still accurate. From 20b235ed644acc3469940d6c4ccf8c70e894ab35 Mon Sep 17 00:00:00 2001 From: Joe Ben <70404172+joebenclark@users.noreply.github.com> Date: Thu, 25 Jun 2026 11:53:58 -0500 Subject: [PATCH 3/3] Update maintainer information in CONTRIBUTING.md --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 355776f..a2596c9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -101,4 +101,4 @@ These views are available in the GitHub Project's **Insights** tab and are refre --- -*This document is maintained by the CDISC IT team. For questions about the estimation process, contact [jbclark@cdisc.org](mailto:jbclark@cdisc.org).* +*This document is maintained by the CDISC Engineering team.