diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..a2596c9 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,104 @@ +# 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. [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) + +--- + +## 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. + +--- + +## Submitting Issues + +When opening a new issue in any `cdisc-org` repository: + +- **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]. + ``` +- **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 are unsure of the right size, pick your best estimate and add a comment explaining your reasoning — a maintainer may adjust it if needed. + +--- + +## 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, 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 + +--- + +## For Outside Collaborators + +Welcome — we are glad to have you. Here is what you need to know: + +- **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. +- **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 Engineering team.