diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000000..7368f60ce3 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1 @@ +* @StackExchange/stacks diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d4d99cd3b9..3c945b335e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,166 +1,152 @@ # Contributing to Stacks -Want to get involved? There are plenty of ways to help! Both internal and external contributors can get involved by submitting new features, fixes, or updates. Before you get started, please take a moment to review this contribution guide. This will make the process easier for everyone involved. +Stacks is Stack Overflow's design system, the shared foundation of components, styles, and guidelines used across Stack Overflow's products. It is maintained by the Stacks team at Stack Overflow. We welcome contributions from both internal and external contributors, whether that's a bug fix, a new component, or a documentation improvement. This guide covers everything you need to get started. ## Table of contents - - [Open an issue](#open-an-issue) + - [Before you start](#before-you-start) - [Reporting bugs](#reporting-bugs) - [Feature requests](#feature-requests) - [Pull requests](#pull-requests) + - [Changesets](#changesets) + - [Merge requirements](#merge-requirements) - [Code guidelines](#code-guidelines) - [License](#license) - - [References](#references) - -## Open an issue - -Before you start anything, we recommend [opening an issue](https://github.com/StackExchange/Stacks/issues/new). This gives the Stacks team and other contributors a chance to provide initial feedback, thoughts, and possible historical context. It may also help you find others who might want to help you out! - -When creating an issue, use following labels to help us out: - - - [`bug`](https://github.com/StackExchange/Stacks/labels/bug) – A _reproducible_ problem with the Stacks code. This will require a build version bump (e.g., `v0.1.1` > `v0.1.2`). - - [`feature`](https://github.com/StackExchange/Stacks/labels/feature) – Issues requesting a new item to Stacks. This will require a minor version bump (e.g., `v0.1.0` > `v0.2.0`). - - [`enhancement`](https://github.com/StackExchange/Stacks/labels/enhancement) – Issues requesting a feature modification or extension. This will require a minor version bump (e.g., `v0.1.0` > `v0.2.0`). - - [`docs`](https://github.com/StackExchange/Stacks/labels/docs) - Issues with the documentation site. - - [`do-not-merge`](https://github.com/StackExchange/Stacks/labels/do-not-merge) - Pull requests that are in progress and should not be merged yet. - - [`help-wanted`](https://github.com/StackExchange/Stacks/labels/help-wanted) – A person would like help with an issue. - - [`setup`](https://github.com/StackExchange/Stacks/labels/setup) – Issues related to Stacks setup and compilation processes. These include items relating to `grunt`, `jekyll`, `postcss`, or other plugins. - - [`status-bydesign`](https://github.com/StackExchange/Stacks/labels/status-bydesign) – Indicates the issue is intentional and not subject to change. - - [`status-completed`](https://github.com/StackExchange/Stacks/labels/status-completed) – Indicates the issue has been resolved. - - [`status-declined`](https://github.com/StackExchange/Stacks/labels/status-declined) – Indicates the issue has been reviewed and will not be addressed at this time. - - [`status-deferred`](https://github.com/StackExchange/Stacks/labels/status-deferred) – Indicates the issue is something that will be addressed, but not in the near term. - - [`status-planned`](https://github.com/StackExchange/Stacks/labels/status-planned) – Indicates the issue has been reviewed and will be addressed in the near team. - - [`status-review`](https://github.com/StackExchange/Stacks/labels/status-review) – Indicates the issue has merit, but a decision either way requires more investigation. - - [`status-reproduced`](https://github.com/StackExchange/Stacks/labels/status-reproduced) – Indicates that the Stacks team were able to reproduce the problem, but cannot address it right now. - - [`status-norepro`](https://github.com/StackExchange/Stacks/labels/status-norepro) – Indicates that the Stacks team were unable to reproduce the problem. - - [`meta`](https://github.com/StackExchange/Stacks/labels/meta) – Issues about Stacks or the GitHub repository. + + +## Before you start + +We recommend filing an issue before diving into a large change. It gives the Stacks team a chance to weigh in early and helps avoid duplicate effort. + + - **Stack Overflow staff:** use the [Stacks Issue Intake form 🔒](https://forms.gle/yYxpXFoE5CSvGVwG9) or the [STACKS Jira board 🔒](https://stackoverflow.atlassian.net/jira/software/projects/STACKS/boards/188) + - **External contributors:** [open a GitHub issue](https://github.com/StackExchange/Stacks/issues/new) ## Reporting bugs -Reporting bugs is a great way to help Stacks. A bug is a _reproducable_ problem with the Stacks code or incorrect (or confusing) documentation. If you’ve found a bug, report it using the following guidelines. Adherence to these guidelines helps us better understand the problem. +A bug is a _reproducible_ problem with the Stacks code or incorrect (or confusing) documentation. If you’ve found one, include the following when you report it: - 1. [**Search previous issues**](https://github.com/StackExchange/Stacks/issues?utf8=%E2%9C%93&q=) — Make sure this issue hasn't already been reported - 2. **What’s the problem?** — If the issue hasn’t been reported, explain what you are trying to do and what actually happened - 3. **Provide an example** — A CodePen that illustrates the problem is perfect - 4. **Describe what you’ve tried so far** — Understanding what you’ve tried so far will help us respond more quickly. Include possible related issues that you’ve read or explored if you can - 5. **Label your issue as a `bug`** + 1. **Search for existing reports**: make sure this issue hasn’t already been reported + 2. **What’s the problem?**: Explain what you are trying to do and what actually happened + 3. **Provide an example**: A CodePen that illustrates the problem is perfect + 4. **Describe what you’ve tried so far**: Understanding what you’ve tried so far will help us respond more quickly. Include possible related issues that you’ve read or explored if you can Issues don’t need to be exhaustive, but we do ask you provide enough details that we can understand the problem and fix the issues. ## Feature requests -Have an idea for how to make Stacks better? Great! We welcome all ideas. There are a few ways you can submit requests: 1) ask us to do it or 2) do it yourself. Either way we do ask that you open an issue first. When opening an issue, provide the following information: +You can request a feature or build it yourself; either way, please file an issue first (see [Before you start](#before-you-start)) and include: 1. **Proposed feature** – What are you proposing? - 2. **Why do you need it?** — Is this required for a project? What’s your timeline? Have you tried using other elements and components first? Explain to us why this needs to be standardized into Stacks. - 3. **Provide examples** — If you have examples how others have solved this problem, provide those so we can better understand what you're asking for. - 4. **Who do you want to create this?** — Are you building this or do you want the Stacks team to build it? - 5. **Label your issue as a `feature`** + 2. **Why do you need it?**: Is this required for a project? What’s your timeline? Have you tried using other elements and components first? Explain to us why this needs to be standardized into Stacks. + 3. **Provide examples**: If you have examples how others have solved this problem, provide those so we can better understand what you’re asking for. + 4. **Who do you want to create this?**: Are you building this or do you want the Stacks team to build it? -Please note that if you are requesting a feature for the Stacks team to build, it will be prioritized against other work. This doesn’t mean it won’t be added. Depending on the request, it could happen rather quickly. But it may also not happen immediately. +If you’re asking the Stacks team to build it, we’ll prioritize it alongside existing work. We can’t guarantee a timeline, but we’ll keep you informed. ## Pull requests -No PR is too small, or too early. We strive to provide initial feedback within a timely manner. Adherence to the following process is the best way to get your work included within Stacks. - -1. **Download Stacks**
- _For **internal** Stack Overflow contributors_, simply clone the repo: - ```bash - # Clone your fork of the repo into the current directory - git clone https://github.com/StackExchange/Stacks.git - # Navigate to the newly cloned directory - cd Stacks - ``` - _For **external** contributors_, [fork](https://help.github.com/fork-a-repo/) the project, clone your fork, and configure the remotes: - ```bash - # Clone your fork of the repo into the current directory - git clone https://github.com//Stacks.git - # Navigate to the newly cloned directory - cd Stacks - # Assign the original repo to a remote called "upstream" - git remote add upstream https://github.com/StackExchange/Stacks.git - ``` - -2. Make sure you have the latest changes from the upstream:
- _For **internal** Stack Overflow contributors:_ - ```bash - git checkout develop - git pull origin develop - ``` - _For **external** contributors:_ - ```bash - git checkout develop - git pull upstream develop - ``` -3. Checkout `develop` branch and create a new topic branch for your feature, change, or fix:
+Please keep PRs focused and reasonably sized. A PR that touches one thing is much easier to review quickly than one that touches many. If you're unsure how to break up a large change, reach out in [#stacks](https://stackexchange.slack.com/archives/C27RWNQN9) (Stack Overflow staff) or [open a GitHub issue](https://github.com/StackExchange/Stacks/issues/new) (external contributors) and we'll help you scope it. Adherence to the following process is the best way to get your work included within Stacks. + +Draft PRs are welcome for work in progress, but we focus our review time on PRs that are marked ready for review. If you'd like early feedback on a draft, just leave a comment asking and we'll take a look. + +### Stack Overflow staff + +1. Clone the repo: + ```bash + git clone https://github.com/StackExchange/Stacks.git + cd Stacks + ``` +2. Pull the latest changes: + ```bash + git checkout main + git pull origin main + ``` +3. Create a topic branch: ```bash - git checkout develop git checkout -b ``` -4. Commit your changes in logical chunks. Please adhere to these [git commit - message guidelines](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) - or your code is unlikely to be merged into the main project. Use Git’s - [interactive rebase](https://help.github.com/articles/interactive-rebase) - feature to tidy up your commits before making them public. -5. Locally merge (or rebase) the upstream development branch into your topic branch:
+4. Commit your changes in logical chunks following [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format (e.g. `fix(button): correct focus ring color`). Use Git’s [interactive rebase](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) to tidy up your commits before making them public. + +5. Sync with main before opening your PR: + ```bash + git pull --rebase origin main + ``` +6. Push your branch and [open a pull request](https://github.com/StackExchange/Stacks/pulls) with a clear title and description. + +### External contributors + +1. [Fork](https://help.github.com/fork-a-repo/) the project, clone your fork, and configure the remotes: + ```bash + git clone https://github.com//Stacks.git + cd Stacks + git remote add upstream https://github.com/StackExchange/Stacks.git + ``` +2. Pull the latest changes: ```bash - git pull --rebase upstream develop + git checkout main + git pull upstream main ``` -6. Push your branch up to your fork: +3. Create a topic branch: ```bash - git push origin + git checkout -b ``` -7. [Open a Pull Request](https://github.com/StackExchange/Stacks/pulls) - with a clear title and description. +4. Commit your changes in logical chunks following [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format (e.g. `fix(button): correct focus ring color`). Use Git’s [interactive rebase](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) to tidy up your commits before making them public. -**Please note** that all pull requests should be merged into the `develop` branch. Any pull request for `production` will be rejected. +5. Sync with upstream before opening your PR: + ```bash + git pull --rebase upstream main + ``` +6. Push your branch and [open a pull request](https://github.com/StackExchange/Stacks/pulls) with a clear title and description. -## Code guidelines +All pull requests should target the `main` branch. Pull requests targeting `production` will be rejected. -### General preferences +## Changesets -We provide an [editor config file](/.editorconfig) to help you adhere to these standards. All files submitted should adhere to these preferences. +Stacks uses [changesets](https://github.com/changesets/changesets) to manage versioning and releases. If your PR includes a change that warrants a new release (a bug fix, new feature, or anything that affects the published packages), you need to include a changeset. - - Use soft tabs with four spaces. - - Nested elements should be indented once (four spaces). - - Trim trailing white space on save. - - Set encoding to UTF-8. - - Add new line at end of files. +Run the following and follow the prompts: -### HTML +```sh +npx changeset +``` -#### Syntax - - Always use double quotes, never single quotes, on attributes. - - Use tags and elements appropriate for an HTML5 doctype (e.g. self-closing tags). - - Use [WAI-ARIA](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) attributes provided in the documentation examples to promote accessibility. - - Don’t omit optional closing tags (e.g. `` or ``). - - In body copy, use smart punctuation. `’` instead of `'`. See [Smart Quotes for Smart People](http://smartquotesforsmartpeople.com/) for more information. - - Copy should be written in sentence-casing (or [downstyle casing](https://en.wiktionary.org/wiki/downstyle#English)). +The [changesets-bot](https://github.com/apps/changeset-bot) will comment on your PR if a changeset is missing. If your change doesn't affect the published packages (e.g. a test file or documentation update), you can safely ignore that message. -#### Attribute Order -HTML attributes should be listed in the following order for easier reading: +## Merge requirements - 1. `class` - 2. `id`, `name` - 3. `data-[name]` - 4. `src`, `for`, `type`, `href`, `value` - 5. `title`, `alt` - 6. `role`, `aria-[name]` +To keep Stacks stable and trustworthy for all the products that depend on it, all contributions must follow these rules without exception, regardless of your role or team. -Classes are reusable so they come first. Ids are more specific and should be used sparingly, so they come second. Order classes the following way: +### Review and merge flow - 1. Atomic classes (In the same fashion as our Less ordering) - 2. Component classes - 3. View classes - 4. JS classes - 5. State classes +1. Open your PR against `main` and mark it ready for review when it's ready. +2. GitHub will automatically request review from `@StackExchange/stacks` for changes covered by `CODEOWNERS`. +3. A Stacks team member will approve the PR or request changes. +4. A Stacks team member will merge the PR once any downstream impact has been assessed. -#### Boolean attributes -A boolean attribute is one that needs no declared value. XHTML required you to declare a value, but HTML5 has no such requirement. If you must include the attribute’s value, and **you don’t need to**, follow this [WhatWG guideline](http://www.whatwg.org/specs/web-apps/current-work/multipage/common-microsyntaxes.html#boolean-attributes): +### PR approvals are required + +All pull requests require at least one approval from a Stacks team member before merging. This applies to everyone, including Stack Overflow employees. If your PR has been open for a while without a review, reach out in [#stacks](https://stackexchange.slack.com/archives/C27RWNQN9) and we'll prioritize it. + +### Do not merge your own PR + +You may not merge a pull request that you authored. This is enforced at the repo level via branch protections. + +### Understand downstream impact before deploying + +Stacks is a dependency for many products across Stack Overflow. Before merging anything that touches the build output or public API, make sure you understand what depends on it and what could break. If you're not sure, ask the Stacks team. We're happy to help you assess the impact and coordinate a safe rollout. - > If the attribute is present, its value must either be the empty string or […] the attribute’s canonical name, with no leading or trailing whitespace. +This is especially important for contributors who are not in the regular engineering workflow. When in doubt, don't deploy. Get in touch first. -*In short, don’t add a value.* +## Code guidelines + +### Formatting + +Code style is enforced automatically by [EditorConfig](/.editorconfig) and [Prettier](https://prettier.io/). Run the formatter before pushing; see the workspace-specific instructions in the README for the exact command. Key settings: 4-space indentation, double quotes, semicolons required, 80-character print width. + +### HTML + +#### Boolean attributes +Don’t add a value to boolean attributes. The HTML spec doesn’t require it. ```html @@ -170,8 +156,8 @@ A boolean attribute is one that needs no declared value. XHTML required you to d ``` -#### Reducing markup -Whenever possible, avoid superfluous parent elements when writing HTML. Many times this requires iteration and refactoring, but produces less HTML. Take the following example: +#### Reduce markup +Avoid superfluous parent elements whenever possible. ```html @@ -183,81 +169,36 @@ Whenever possible, avoid superfluous parent elements when writing HTML. Many tim ``` -#### Javascript-generated markup -Writing markup in a JavaScript file makes the content harder to find, harder to edit, and less performant. Avoid it whenever possible. +#### Accessibility +Use [WAI-ARIA](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) attributes as shown in the documentation examples. Copy should be written in sentence case. See our [org-wide accessibility targets 🔒](https://docs.google.com/document/d/1KCLvgy_ijJCUJXaVV2uh6wwsl1hoahFmPU7Gwnk0yug/edit?usp=sharing) and [accessibility testing strategy](https://github.com/StackExchange/Stacks/blob/main/adrs/0004-accessibility-testing-strategy.md) for our standards and approach. -### CSS / Less +### TypeScript -#### Syntax - - Use a variable. You shouldn’t be hard-coding pixel values or colors. - - When commenting, use `// Double slash` comments instead of `/* Slash star */`. - - When grouping selectors, keep individual selectors on their own line. - - Include one space before the opening brace of declaration blocks for legibility. - - Place closing braces of declaration blocks on a new line. - - Include one space after `:` for each declaration. - - Each declaration should appear on its own line for more accurate error reporting. - - End all declarations with a semi-colon. The last declaration’s is optional, but your code is more error prone without it. - - Comma-separated property values should include a space after each comma (e.g., `box-shadow`). - - Include spaces after commas within `rgb()`, `rgba()`, `hsl()`, `hsla()`, or `rect()` values. - - Prefix property values or color parameters with a leading zero (e.g., `.5` should be `0.5` and `-.5px` should be `-0.5px`). - - Use our pre-defined color variables instead of hard-coding hex values where possible. - - Quote attribute values in selectors, e.g., `input[type="text"]`. [They’re only optional in some cases](http://mathiasbynens.be/notes/unquoted-attribute-values#css), and it’s a good practice for consistency. - - Generally, we should avoid specifying `0` as a value, but when doing so avoid specifying units for zero values, e.g., `margin: 0;` instead of `margin: 0px;`. - - Do not use atomic classes as mixins - -#### Declaration Order -Instead of ordering declarations alphabetically, we logically group items together. [Field Manuals](https://manuals.gravitydept.com/code/css/properties) does a great job explaining this idea. Ordering Less this way helps people to understand maintain the code. - -The ordering works from outside the box to inside the box: - -| Group | Decision being made | Property examples | -| -------------- | --------------------- | -------------------------------- | -| 1. Generated content | Items like `:before`/`:after` are listed first. | `content`, `list-style`, `quotes` | -| 2. Flow Context
3. Position Model
4. Float Model
5. Flex Model
6. Grid Model | Interplay and relationship between boxes | `display`, `overflow`, `visibility`
`clip`, `position`, `z-index`, `top`
`clear`, `float`
`flex`, `align-content`, `order`
`grid`, `grid-gap`, `grid-template` | -| 7. Box Model | Dimensions of the box | `box-sizing`, `width`, `height`, `margin`, `padding`, `border` | -| 8. Visual Box | How the box appears | `background`, `box-shadow`, `opacity`, `outline` | -| 9. Typography | Font and color appearance | `color`, `font-size`, `line-height`, `text-align`, `vertical-align`, `white-space` | -| 10. Animation
11. Transform
12. Transition | Changing the box's representation 2D/3D/4D | `animation`, `animation-delay`
`backface-visibility`, `perspective`, `transform`
`transition`, `transition-delay` | -| 13. Will Change | Rendering optimization | `will-change` | -| 14. Pointer + Selection | Modify the user's input tool | `appearance`, `cursor`, `pointer-events` | - -For the most part you will not have to worry about this because PostCSS automatically reorders all Less files for you. - -#### Shorthand Notation -Avoid using shorthand declaration unless you are explicitly setting all the available values. Commonly overused shorthand properties include: - - - `padding` - - `margin` - - `font` - - `background` - - `border` - - `border-radius` - -Typically you don’t need to set all the values the shorthand property represents. Shorthand properties have a higher specificity than their longform counterparts. They also reset undeclared property values, which leads to unintended side effects. The Mozilla Developer Network has a [great article on shorthand properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties) for those unfamiliar with notation and behavior. - -```css -// Avoid this -.element { - margin: 0 0 10px; - background: red; - background: url("image.jpg"); - border-radius: 3px 3px 0 0; -} - -// Do this -.element { - margin-bottom: 10px; - background-color: red; - background-image: url("image.jpg"); - border-top-left-radius: 3px; - border-top-right-radius: 3px; -} -``` + - All new code should be written in TypeScript. Strict mode is enabled across all packages. + - Avoid `any`. Use `unknown` or explicit types instead. + - Prefer explicit return types on exported functions and component props. -## License +### Svelte + + - Use Svelte 5 [runes](https://svelte.dev/docs/svelte/what-are-runes) syntax: `$state`, `$derived`, `$effect`. + - Do not use legacy `export let` props or `$:` reactive statements. + - Follow the patterns established in existing components for consistency. + +### JavaScript -By contributing to Stacks, you agree to license your work under Stacks’ [MIT License](https://github.com/StackExchange/Stacks/blob/production/LICENSE.MD). + - Do not use `console`, `alert`, `confirm`, or `prompt` (these are ESLint errors). + - Avoid generating markup in JavaScript. It’s harder to find, harder to edit, and harder to maintain. -## References +### CSS / Less + +#### Variables and values + - Use pre-defined color and spacing variables; don’t hard-code hex values or pixel values. See the [pseudo private custom properties ADR](https://github.com/StackExchange/Stacks/blob/main/adrs/0001-pseudo-private-custom-properties.md) for how we use CSS custom properties. + - Use `//` comments instead of `/* */`. + - Do not use atomic classes as mixins. + - Omit units on zero values, e.g. `margin: 0;` not `margin: 0px;`. + - Do not use `js-*` selectors for visual styling; they are reserved for JavaScript hooks. + + +## License -The following contribution guides were used as references when creating this one: [Grommet](https://github.com/grommet/grommet/blob/production/CONTRIBUTING.md), [Salesforce Lightning Design System](https://github.com/salesforce-ux/design-system/blob/production/CONTRIBUTING.md), and [Bootstrap](https://github.com/twbs/bootstrap/blob/production/CONTRIBUTING.md). +By contributing to Stacks, you agree to license your work under Stacks’ [MIT License](https://github.com/StackExchange/Stacks/blob/main/LICENSE.MD). diff --git a/README.md b/README.md index 395aff6a76..67765f33af 100755 --- a/README.md +++ b/README.md @@ -1,38 +1,39 @@ # Stacks -Stacks is Stack Overflow’s design system. It includes the resources needed to create consistent, predictable interfaces and workflows that conform to Stack Overflow’s principles, design language, and best practices. - -Our documentation is built with Stacks itself, using its [immutable, atomic classes](http://johnpolacek.com/rethinking/) and components. +Stacks is Stack Overflow's design system, the shared foundation of components, styles, and guidelines used across Stack Overflow's products. For usage instructions, see our [usage guidelines](https://stackoverflow.design/system/develop/using-stacks). ## Table of contents -- [Using Stacks](#using-stacks) +- [Contributing](#contributing) - [Local Development](#local-development) -- [Stacks Docs](#stacks-docs) -- [Stacks Classic](#stacks-classic) -- [Stacks Svelte](#stacks-svelte) + - [Stacks Docs](#stacks-docs) + - [Stacks Classic](#stacks-classic) + - [Stacks Svelte](#stacks-svelte) - [Releasing Stacks](#releasing-stacks) -- [Bugs and feature requests](#bugs-and-feature-requests) -- [Contributing](#contributing) - [License](#license) -# Using Stacks -Using Stacks is outlined in our [usage guidelines](https://stackoverflow.design/system/develop/using-stacks). +## Contributing +Please read through our **[contribution guidelines](/CONTRIBUTING.md)** before getting started. The guide covers: + +- [Before you start](/CONTRIBUTING.md#before-you-start): where to report bugs or request features +- [Pull requests](/CONTRIBUTING.md#pull-requests): how to set up and submit your work +- [Merge requirements](/CONTRIBUTING.md#merge-requirements): required approvals and deployment rules that apply to everyone +- [Code guidelines](/CONTRIBUTING.md#code-guidelines): formatting and style conventions -# Local Development +## Local Development -This repo follows a monolithic structure and contains multiple packages split into [npm workspaces](https://docs.npmjs.com/cli/v9/using-npm/workspaces). These can be found under the [packages/](https://github.com/StackExchange/Stacks/tree/develop/packages) folder. +This repo follows a monolithic structure and contains multiple packages split into [npm workspaces](https://docs.npmjs.com/cli/v9/using-npm/workspaces). These can be found under the [packages/](https://github.com/StackExchange/Stacks/tree/main/packages) folder. To get any of these Stacks workspaces working locally start out by installing all required dependencies: ```sh npm i ``` -Below are instructions on how to build and test each individual workspace. If you have trouble getting any of these steps to work, please open [an issue](https://github.com/StackExchange/Stacks/issues/new) with a `setup` label. +Below are instructions on how to build and test each individual workspace. If you run into trouble, see [Before you start](/CONTRIBUTING.md#before-you-start) in our contributing guide for how to reach us. -## Stacks Docs +### Stacks Docs -This workspace contains the Stacks documentation project that’s hosted on: https://stackoverflow.design/ +This workspace contains the Stacks documentation project that's hosted on: https://stackoverflow.design/ To contribute to Stacks documentation you can build locally via: ```sh @@ -40,20 +41,20 @@ npm start ``` This command will pull up the local dev server at http://localhost:5173/. You can also view our [building guidelines](https://stackoverflow.design/system/develop/building). -## Stacks Classic +### Stacks Classic [![ci status][gh-action-badge]][gh-action-url] [![npm version][npm-badge]][npm-url] This workspace contains the css and js sources that define and power the Stacks design system. -### Formatting +#### Formatting Format the source code with prettier by running: ```sh npm run format -w packages/stacks-classic ``` -### Linting +#### Linting Run all lint suites by running: ```sh @@ -72,16 +73,16 @@ Lint the source code format (prettier) via running: npm run lint:format -w packages/stacks-classic ``` -### Testing +#### Testing Run all test suites by running: ```sh npm run test -w packages/stacks-classic ``` -#### Unit/Component Tests +##### Unit/Component Tests Unit/Component tests are written with [DOM Testing Library](https://testing-library.com/docs/dom-testing-library/intro). -Please follow the library’s principles and documentation to write tests. +Please follow the library's principles and documentation to write tests. Stacks uses [Web Test Runner](https://modern-web.dev/docs/test-runner/overview/) and [Playwright](https://modern-web.dev/docs/test-runner/browser-launchers/playwright/) to run tests in a real browser context. @@ -94,9 +95,9 @@ or if you prefer watch mode run: npm run test:unit:watch -w packages/stacks-classic ``` -#### Visual Regression Tests +##### Visual Regression Tests -**Prerequisites:** +**Prerequisites:** - `git lfs` ([installation docs](https://docs.github.com/en/repositories/working-with-files/managing-large-files/installing-git-large-file-storage)) - `docker` ([installation docs](https://docs.docker.com/engine/install/)) - `pwsh` ([Installation docs](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.3)) @@ -109,14 +110,14 @@ Execute the visual regression tests suite by running: ```sh npm run test:visual -w packages/stacks-classic ``` -After the first run, if there are failing snapshots, they end up overriding the baseline ones in the filesystem (e.g. `/screenshots//baseline/.png`). +After the first run, if there are failing snapshots, they end up overriding the baseline ones in the filesystem (e.g. `/screenshots//baseline/.png`). We do this for easier comparison of the dif directly in vscode and to make sure only the failing snapshots get regenerated (see [this GH discussion](https://github.com/modernweb-dev/web/discussions/427#discussioncomment-3543771) that inspired the approach). We also recommend to install [this vscode extension](https://marketplace.visualstudio.com/items?itemName=RayWiis.png-image-diff) for getting better diffs. -#### Less Tests +##### Less Tests -This is an experimental suite to test the generation of CSS from Less files. +This is an experimental suite to test the generation of CSS from Less files. Less tests end with this suffix `*.less.test.ts`. Execute the less tests suite by running: @@ -129,7 +130,7 @@ Update the css snapshots via: npm run test:less:update -w packages/stacks-classic ``` -## Stacks Svelte +### Stacks Svelte [![ci status][gh-action-badge]][gh-action-url] [![npm version][npm-badge-svelte]][npm-url-svelte] @@ -144,19 +145,19 @@ npm run storybook -w packages/stacks-svelte The storybook server will reflect the changes you make to the components stories in real time. We use [this addon](https://storybook.js.org/addons/@storybook/addon-svelte-csf) to write stories directly in Svelte syntax. Stories need to have the `*.stories.svelte` extension to be picked up. -### Formatting +#### Formatting ```bash npm run format -w packages/stacks-svelte ``` -### Linting +#### Linting ```bash npm run lint -w packages/stacks-svelte ``` -### Testing +#### Testing Stacks Svelte uses [Web Test Runner](https://modern-web.dev/docs/test-runner/overview/) and [Playwright](https://modern-web.dev/docs/test-runner/browser-launchers/playwright/) to run tests in a real browser context. @@ -170,49 +171,27 @@ or to run the tests in watch mode: npm run test:watch -w packages/stacks-svelte ``` -# Releasing Stacks -This repo uses [Semantic Versioning](https://semver.org/) to distribute Stacks Classic and Stacks Docs via [npm](https://www.npmjs.com/package/@stackoverflow/stacks), and publishes [release notes on Github](https://github.com/StackExchange/Stacks/releases). +## Releasing Stacks +This repo uses [Semantic Versioning](https://semver.org/) to distribute Stacks Classic and Stacks Docs via [npm](https://www.npmjs.com/package/@stackoverflow/stacks), and publishes [release notes on Github](https://github.com/StackExchange/Stacks/releases). We use [changesets](https://github.com/changesets/changesets) to automatize the steps necessary to publish to NPM, create GH releases and a changelog. -- Every time you do work that requires a new release to be published, [add a changesets entry](https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md) by running `npx changeset` and follow the instructions on screen. (changes that do not require a new release - e.g. changing a test file - don’t need a changeset). +- Every time you do work that requires a new release to be published, [add a changesets entry](https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md) by running `npx changeset` and follow the instructions on screen. (changes that do not require a new release - e.g. changing a test file - don't need a changeset). - When opening a PR without a corresponding changeset the [changesets-bot](https://github.com/apps/changeset-bot) will remind you to do so. It generally makes sense to have one changeset for PR (if the PR changes do not require a new release to be published the bot message can be safely ignored) -- The [release github workflow](.github/workflows/release.yml) continuosly check if there are new pending changesets in the main branch, if there are it creates a GH PR (`chore(release)` [see example](https://github.com/StackExchange/apca-check/pull/2)) and continue updating it as more changesets are potentially pushed/merged to the main branch. -- When we are ready to cut a release we need to simply merge the `chore(release)` PR back to main and the release github workflow will take care of publishing the changes to NPM and create a GH release for us. The `chore(release)` PR also give us an opportunity to adjust the automatically generated changelog when necessary (the entry in the changelog file is also what will end up in the GH release notes). +- The [release github workflow](.github/workflows/main.yml) continuously checks if there are new pending changesets in the `beta` branch; if there are, it creates a GH PR (`chore(release)` [see example](https://github.com/StackExchange/apca-check/pull/2)) and continues updating it as more changesets are pushed/merged to the `beta` branch. +- When we are ready to cut a release we need to simply merge the `chore(release)` PR and the release github workflow will take care of publishing the changes to NPM and create a GH release for us. The `chore(release)` PR also give us an opportunity to adjust the automatically generated changelog when necessary (the entry in the changelog file is also what will end up in the GH release notes). _The release github workflow only run if the CI workflow (running linter, formatter and tests) is successful: CI is blocking accidental releases_. _Despite using changesets to communicate the intent of creating releases in a more explicit way, we still follow [conventional commits standards](https://www.conventionalcommits.org/en/v1.0.0/) for keeping our git history easily parseable by the human eye._ -Successful releases trigger automatically a new deployment to stackoverflow.design by merging the `develop` branch into the `production` branch. - -## Beta publishing -We use Changesets in prerelease mode to manage publishing to the beta branch. For more information, please refer to the official [Changesets prerelease documentation](https://github.com/changesets/changesets/blob/main/docs/prereleases.md). - -To prepare a beta release, follow these steps: - -1. Create a pull request (PR) targeting the beta branch. - -2. Ensure your PR includes a changeset. - -3. Merging the PR will trigger the `release` job. This job creates or updates a chore(new-beta-release) PR. - -4. To cut a new beta release, merge the `chore(new-release) (beta)` PR and wait for the `Release (latest or beta)` job to complete. - -Consumers can install the beta package by targeting the beta tag: -`npm install @stackoverflow/stacks@beta` or `npm install @stackoverflow/stacks-svelte@beta` - -## Bugs and feature requests -Have a bug or feature request? First search existing or closed issues to make sure the issue hasn’t been noted yet. If not, review our [issue guidelines](/CONTRIBUTING.md#open-an-issue) for submitting [a bug report](/CONTRIBUTING.md#reporting-bugs) or [feature request](/CONTRIBUTING.md#feature-requests). - -## Contributing -If you’d like to contribute to Stacks, please read through our [contribution guidelines](/CONTRIBUTING.md). Included are directions for opening issues, coding standards, and notes on development. +Successful releases trigger automatically a new deployment to stackoverflow.design by merging the `main` branch. ## License -Code and documentation copyright 2017-2024 Stack Exchange, Inc and released under the [MIT License](/LICENSE.MD). +Code and documentation copyright 2017-2026 Stack Exchange, Inc and released under the [MIT License](/LICENSE.MD). [gh-action-url]: https://github.com/StackExchange/Stacks/actions/workflows/main.yml -[gh-action-badge]: https://github.com/StackExchange/Stacks/actions/workflows/workflow.yml/badge.svg?branch=develop +[gh-action-badge]: https://github.com/StackExchange/Stacks/actions/workflows/main.yml/badge.svg?branch=main [npm-url]: https://npmjs.org/package/@stackoverflow/stacks [npm-badge]: https://img.shields.io/npm/v/@stackoverflow/stacks.svg