Skip to content

Commit 234695c

Browse files
graynortongraynorton
committed
chore: add contributor docs (WIP)
1 parent 5dcdae8 commit 234695c

File tree

23 files changed

+1986
-0
lines changed

23 files changed

+1986
-0
lines changed

‎.cursor/rules/contributor-doc-update.mdc‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
description: Useful for updating auto-generated content in the contributor docs
3+
alwaysApply: false
4+
---
5+
If the user requests an update to the contributor docs (located in the CONTRIBUTOR_DOCS folder at the repository root), run the update process as described in the agent instructions within that folder.
6+
7+
To locate the instructions, search for "ai-agent-instructions", or fall back to a recursive directory search if needed.

‎CONTRIBUTOR-DOCS/01_objectives-and-strategy.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
<!-- Generated breadcrumbs - DO NOT EDIT -->
2+
3+
[CONTRIBUTOR-DOCS](README.md) / Objectives and Strategy
4+
5+
<!-- Document title (editable) -->
6+
7+
# Objectives and Strategy
8+
9+
<!-- Generated TOC - DO NOT EDIT -->
10+
11+
<details open>
12+
<summary><strong>In this doc</strong></summary>
13+
14+
- [Current Objectives](#current-objectives)
15+
- [Unify Spectrum CSS & Spectrum Web Components](#unify-spectrum-css--spectrum-web-components)
16+
- [Build a clean foundation for future work](#build-a-clean-foundation-for-future-work)
17+
- [Enable Spectrum 2 adoption](#enable-spectrum-2-adoption)
18+
- [Improve accessibility](#improve-accessibility)
19+
- [Continually improve components](#continually-improve-components)
20+
- [Strategy](#strategy)
21+
- [Disruptive vs. non-disruptive change](#disruptive-vs-non-disruptive-change)
22+
- [Side-by-side development of 1st-gen and 2nd-gen](#side-by-side-development-of-1st-gen-and-2nd-gen)
23+
24+
</details>
25+
26+
<!-- Document content (editable) -->
27+
28+
## Current Objectives
29+
30+
The SWC project is currently focused on a relatively small set of strategic objectives:
31+
32+
### Unify Spectrum CSS & Spectrum Web Components
33+
34+
Integrate the formerly separate Spectrum CSS and SWC projects, forming a unified project with a single code base, delivering a single product that is laser-focused on the needs of our target customers.
35+
36+
### Build a clean foundation for future work
37+
38+
Improve tooling, infrastructure, and cross-cutting product layers:
39+
40+
- Replace old, poorly supported tool chains and custom scripts with widely adopted, modern, turnkey solutions.
41+
42+
- Simplify and improve our style-loading, theming, and customization capabilities.
43+
44+
- Integrate and improve our documentation and Storybook.
45+
46+
- Reduce complexity wherever possible.
47+
48+
### Enable Spectrum 2 adoption
49+
50+
Enable our customers to ship Spectrum-2-based products, working toward a full-fidelity Spectrum 2 implementation while making the path to Spectrum 2 adoption as smooth as possible for customers.
51+
52+
This is a two-phase process:
53+
54+
- **Phase 1:** Deliver a stable, production-quality Spectrum 2 implementation within our 1st-gen product, offering foundational S2 fidelity via the `spectrum-two` theme while avoiding breaking API and layout changes.
55+
56+
This phase is essentially complete, although some refinement of the `spectrum-two` theme continues.
57+
58+
- **Phase 2:** Deliver a full-fidelity Spectrum 2 implementation as part of our 2nd-gen product.
59+
60+
This will entail some breaking changes, but to facilitate incremental migration on a view-by-view or component-by-component basis, it will be possible for customers to use 1st-gen and 2nd-gen SWC components together within a single project.
61+
62+
### Improve accessibility
63+
64+
Systematically improve accessibility by expanding documentation and examples, completing a comprehensive audit to address issues, and generally striving to maximize accessibility across all components.
65+
66+
### Continually improve components
67+
68+
Make improvements of all types and sizes to our components, including bug fixes, feature enhancements, improvements to API clarity and consistency, and major refactoring or replacement as needed.
69+
70+
## Strategy
71+
72+
From a value point of view, the objectives above are largely independent of one other. We want to keep them loosely coupled so that we can advance each according to its own priority, and so that work toward one objective doesn't needlessly block work toward another—for example, full-fidelity Spectrum 2 work shouldn't block accessibility work, and vice versa.
73+
74+
At a high level, our strategy for efficiently pursuing our objectives in parallel is to:
75+
76+
- Differentiate inherently disruptive changes from non-disruptive changes.
77+
78+
- Channel disruptive changes into 2nd-gen, where we can take the time to get them right and the care to minimize the disruption they actually cause.
79+
80+
- Work on 1st-gen and 2nd-gen side-by-side, so that non-disruptive changes can easily be shared between generations and delivered continually throughout the transition.
81+
82+
### Disruptive vs. non-disruptive change
83+
84+
Our first three objectives have aspects that are inherently disruptive, or have the potential to cause significant disruption—to the project, its customers, or both:
85+
86+
- **Unifying Spectrum CSS and SWC** involves consolidating our work from two projects and repositories into one and making significant changes to the shape of our product offerings.
87+
88+
- **Building a clean foundation for the future** entails making major changes to our workflows and tooling, the packages we ship, and cross-cutting product features like style-loading, theming and customization.
89+
90+
- **Landing full-fidelity Spectrum 2 in SWC** will necessitate some breaking changes stemming from the design itself—changes to design tokens, and to the features, APIs and layout footprints of certain components.
91+
92+
Meanwhile, most of the **accessibility improvements** and general **component improvements** we want to make aren't inherently disruptive—they can delivered in a continual stream of targeted, mostly non-breaking releases.
93+
94+
### Side-by-side development of 1st-gen and 2nd-gen
95+
96+
We have decided to work on 1st-gen and 2nd-gen side-by-side, in the same repository. This gives us two important advantages: **isolation** and **colocation**.
97+
98+
**Isolation** of 1st-gen and 2nd-gen in separate workspaces lets us build 2nd-gen iteratively from the ground up, leaving behind as much structural and technical debt as possible, without needing to worry about breaking 1st-gen. Disruptive changes are confined to the `second-gen` workspace, while the 1st-gen project continues working essentially "as-is."
99+
100+
**Colocation** of 1st-gen and 2nd-gen in a single branch of the same repository makes it easy to share core component functionality between generations. Here's how this works:
101+
102+
- We locate core component implementations in the 2nd-gen Core library as **abstract, non-rendering classes**.
103+
104+
These classes define **shared API** and implement **generation-agnostic behavior and logic**.
105+
106+
- In both 1st-gen and 2nd-gen SWC, we implement components as **concrete, rendering classes** that extend from the abstract classes in Core.
107+
108+
These classes implement **generation-specific rendering and styling**, and **override API and behavior** as needed.
109+
110+
This architecture delivers two key benefits:
111+
112+
1. **Improvements we make in shared code immediately benefit 1st-gen SWC customers,** letting us deliver value on a continual basis throughout the transition.
113+
114+
2. **Sharing code will help make customers' eventual migration from 1st-gen to 2nd-gen as smooth as possible.** By design, it will be difficult to introduce unnecessary or unintentional API or functional differences between 1st- and 2nd-gen components.

‎CONTRIBUTOR-DOCS/02_contributor-guides/01_code-of-conduct.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
<!-- Generated breadcrumbs - DO NOT EDIT -->
2+
3+
[CONTRIBUTOR-DOCS](../README.md) / [Contributor Guides](README.md) / Adobe Code of Conduct
4+
5+
<!-- Document title (editable) -->
6+
7+
# Adobe Code of Conduct
8+
9+
<!-- Generated TOC - DO NOT EDIT -->
10+
11+
<details open>
12+
<summary><strong>In this doc</strong></summary>
13+
14+
- [Our Pledge](#our-pledge)
15+
- [Our Standards](#our-standards)
16+
- [Our Responsibilities](#our-responsibilities)
17+
- [Scope](#scope)
18+
- [Enforcement](#enforcement)
19+
- [Attribution](#attribution)
20+
21+
</details>
22+
23+
<!-- Document content (editable) -->
24+
25+
## Our Pledge
26+
27+
In the interest of fostering an open and welcoming environment, we as
28+
contributors and maintainers pledge to make participation in our project and
29+
our community a harassment-free experience for everyone, regardless of age, body
30+
size, disability, ethnicity, gender identity and expression, level of experience,
31+
nationality, personal appearance, race, religion, or sexual identity and
32+
orientation.
33+
34+
## Our Standards
35+
36+
Examples of behavior that contributes to creating a positive environment
37+
include:
38+
39+
- Using welcoming and inclusive language
40+
- Being respectful of differing viewpoints and experiences
41+
- Gracefully accepting constructive criticism
42+
- Focusing on what is best for the community
43+
- Showing empathy towards other community members
44+
45+
Examples of unacceptable behavior by participants include:
46+
47+
- The use of sexualized language or imagery and unwelcome sexual attention or
48+
advances
49+
- Trolling, insulting/derogatory comments, and personal or political attacks
50+
- Public or private harassment
51+
- Publishing others' private information, such as a physical or electronic
52+
address, without explicit permission
53+
- Other conduct which could reasonably be considered inappropriate in a
54+
professional setting
55+
56+
## Our Responsibilities
57+
58+
Project maintainers are responsible for clarifying the standards of acceptable
59+
behavior and are expected to take appropriate and fair corrective action in
60+
response to any instances of unacceptable behavior.
61+
62+
Project maintainers have the right and responsibility to remove, edit, or
63+
reject comments, commits, code, wiki edits, issues, and other contributions
64+
that are not aligned to this Code of Conduct, or to ban temporarily or
65+
permanently any contributor for other behaviors that they deem inappropriate,
66+
threatening, offensive, or harmful.
67+
68+
## Scope
69+
70+
This Code of Conduct applies both within project spaces and in public spaces
71+
when an individual is representing the project or its community. Examples of
72+
representing a project or community include using an official project e-mail
73+
address, posting via an official social media account, or acting as an appointed
74+
representative at an online or offline event. Representation of a project may be
75+
further defined and clarified by project maintainers.
76+
77+
## Enforcement
78+
79+
Instances of abusive, harassing, or otherwise, unacceptable behavior may be
80+
reported by contacting the project team at Grp-opensourceoffice@adobe.com. All
81+
complaints will be reviewed and investigated and will result in a response that
82+
is deemed necessary and appropriate to the circumstances. The project team is
83+
obligated to maintain confidentiality concerning the reporter of an incident.
84+
Further details of specific enforcement policies may be posted separately.
85+
86+
Project maintainers who do not follow or enforce the Code of Conduct in good
87+
faith may face temporary or permanent repercussions as determined by other
88+
members of the project's leadership.
89+
90+
## Attribution
91+
92+
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
93+
available at [http://contributor-covenant.org/version/1/4][version]
94+
95+
[homepage]: http://contributor-covenant.org
96+
[version]: http://contributor-covenant.org/version/1/4/

‎CONTRIBUTOR-DOCS/02_contributor-guides/README.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
<!-- Generated breadcrumbs - DO NOT EDIT -->
2+
3+
[CONTRIBUTOR-DOCS](../README.md) / Contributor Guides
4+
5+
<!-- Document title (editable) -->
6+
7+
# Contributor Guides
8+
9+
<!-- Generated TOC - DO NOT EDIT -->
10+
11+
<details open>
12+
<summary><strong>Beneath this doc</strong></summary>
13+
14+
- [Adobe Code of Conduct](01_code-of-conduct.md)
15+
- [Authoring contributor docs](authoring-contributor-docs/README.md)
16+
- [AI agent instructions](authoring-contributor-docs/01_ai-agent-instructions.md)
17+
18+
</details>
19+
20+
<!-- Document content (editable) -->
21+
22+
(Content to be added)

0 commit comments

Comments
 (0)