Change 801816 had a related patch set uploaded (by Anne Tomasevich; author: Catrope):

[design/codex@main] build: Add separate entry point for experimental components

https://gerrit.wikimedia.org/r/801816

@Catrope @egardner please feel free to edit this task as you see fit

Change 822143 had a related patch set uploaded (by Catrope; author: Catrope):

[design/codex@main] docs: Hide experimental components in the release docs

https://gerrit.wikimedia.org/r/822143

Change 822144 had a related patch set uploaded (by Catrope; author: Catrope):

[integration/config@master] Zuul: [design/codex] Run special doc command for release tags

https://gerrit.wikimedia.org/r/822144

The attached patches implement my proposed approach to experimental components. This patch demonstrates how it would work by marking the Combobox component as experimental.

Here's the process I propose:

• An initial implementation of a component that is incomplete/experimental should:
  • Add the component to lib-experimental.ts (but not to lib.ts). This keeps it out of the release build of the library, but makes it available to the docs site.
  • Add a simple demo for the component to the sandbox, by creating demo/ComponentNameDemo.vue and adding that to demo/Sandbox.vue
    • ComponentNameDemo.vue should import the component from ../lib-experimental (unlike demos for established components, which import from ../lib)
  • Add a basic test file that just does a simple snapshot test
• As the implementation matures, a docs page (component-demos/component-name.md) with demos should be added at some point
  • The entry for this docs page in the sidebar config in docs/.vitepress/config.js should set experimental: true.
  • This ensures the page is excluded from the sidebar in release builds of the docs site (e.g. https://doc.wikimedia.org/codex/v0.1.0-alpha.9). It will still be included in other builds of the docs site (the one at https://doc.wikimedia.org/codex/main , Netlify deployment previews for unmerged patches, and in local development with npm run doc:dev).
• Once the implementation is mature enough, its experimental status is removed. This involves:
  • Moving the component export from lib-experimental.ts to lib.ts
  • Changing its sandbox demo to import from ../lib instead of ../lib-experimental.
  • Removing its experimental: true flag in the Vitepress sidebar config

Open questions:

• Should we put experimental components in their own subdirectory, e.g. src/components/experimental/component-name/ComponentName.vue or src/components-experimental/component-name/ComponentName.vue?
  • This would make it easier to set different test coverage standards for experimental vs non-experimental components
  • This would make it easier to programmatically detect whether a component is experimental
  • This would make it easier to notice when a non-experimental component imports an experimental one, which should not be allowed (and this could even be enforced by eslint)
  • However, it would require moving the directory and updating file path references when promoting a component out of experimental status
• Should we encourage sidebar demos to import directly from the component file, rather than from ../lib?
  • This would match other internal imports in Codex; nothing else imports from lib.ts directly
  • This would avoid having to update the demo file when a component is promoted out of experimental status
  • However, demos using multiple components or using types would no longer be able to import everything on one line

This work suggests we should prioritize the resolution T311097, so we can provide https://doc.wikimedia.org/codex/latest or something similar as the preferred version of the Codex docs site for most Codex users to view (rather than the main branch, which will contain experimental components)

For the open questions, I don't feel super strongly about either of them, but I think:

• It's fine to put experimental components in their own directory even if it means we have to move the files and adjust file paths when they graduate
• It's fine to import directly from component files instead of lib in demo page files even if it means additional lines of code

Change 823269 had a related patch set uploaded (by Catrope; author: Catrope):

[design/codex@main] docs: Don't error when a component-demos .md file doesn't exist

https://gerrit.wikimedia.org/r/823269

We discussed this yesterday and decided we should approach this medium-sized decision as an ADR - research alternatives, then fill out this template with a focus on user impact. For now we'll store this ADR in this ticket

Draft ADR below. I think the approach part reflects the consensus from the discussion on the task above and from our meetings. The name is my own proposal that I haven't yet run by anyone, after hearing that "experimental" was a confusing term. Very happy to amend any part of this in response to feedback.

Infrastructure for work-in-progress (WIP_ co

• Status: proposed
• Deciders: @Catrope, @AnneT, @egardner, @Volker_E
• Date: 2022-08-16
• Task: T313767

Context and problem statement

We would like to be able to build new components iteratively, and to accept patches introducing new components that are not complete. To this end, we would like to be able to have incomplete component code live in the Codex repository, but not be included in releases or otherwise pose risks to mature code.

Decision drivers

• Clear nomenclature, with room for expansion for more maturity stages that we may want to add in the future
• The process for adding a new component should be easy to understand, and not require too many steps
• Promoting a component from "in development" to "part of the library" should not require too many steps
• While a component is in the development stage, it should be clear to everyone (developers and library users) that it is in that state, and what that means

Considered options

Name:

• "Experimental components"
• "Components in development"
• "Work in progress" (WIP)

Mechanics:

• Option 1: same directory, different entry point
  • Experimental/dev components live in the same directory as regular components, i.e. src/components/foo-bar/FooBar.vue
  • Experimental/dev components are not exported in the lib.ts entry point. Instead ,they are exported in a different entry point file (lib-experimental.ts or lib-development.ts)
  • Experimental/dev components are added to the Vitepress sidebar config in docs/.vitepress/config.js, but their entry must be marked with the experimental: true flag
• Option 2: different directories
  • Experimental/dev components live in a different directory, e.g. src/components-experimental/foo-bar/FooBar.vue or src/components-development/foo-bar/FooBar.vue
  • Experimental/dev components are not exported in the lib.ts entry point. Instead, they are exported in an index file for their special directory (src/components-experimental/index.ts or src/components-development/index.ts)
  • Experimental/dev components are listed in the Vitepress sidebar config in docs/.vitepress/config.js just like regular components. They are automatically detected as experimental based on their file path, and marked as such (in development builds of the documentation) or hidden (in release builds of the documentation).

Decision outcome

For the name, we chose "work in progress", because it's more clearly communicates "not ready yet, but will be ready in the future", whereas "experimental" is more tentative and "in development" is not very clear (because even "finished" components still have development happen to them). We may also want to use "experimental" as a separate maturity stage later.

For the approach, we chose option 2 (different directories), because that makes it clearer to developers which components are still in development, and makes it easier for automated tools to treat those components differently. The directory will be called components-wip.

Positive consequences

• The docs site will be able to automatically detect WIP components and treat them differently based on their file path
• We'll be able to use eslint to prohibit non-WIP code from importing WIP code
• If desired, we'll be able to set different unit test coverage thresholds for WIP code vs regular code

Negative consequences

• Graduating a component from WIP status to stable status requires moving all of its files to another directory

Pros and cons of the options

Option 1: same directory

• Good: Simpler directory structure, no file renaming involved
• Bad: Makes it more difficult to programmatically detect whether a component is a work in progress

Option 2: different directories

• Good: Easy detection of WIP components
• Good: Directory-based distinction works with more tools (e.g. eslint, jest)
• Bad: Some tools (e.g. vue-docgen) have to look in two directories
• Bad: Files have to be renamed when graduating to stable status

Change 823269 merged by jenkins-bot:

[design/codex@main] docs: Don't error when a component-demos .md file doesn't exist

https://gerrit.wikimedia.org/r/823269

This looks great, thanks for putting it all together! I think either option would be acceptable but support option 2 more because of its clear distinction between stages of maturity both for the sake of our tools and for ourselves.

components-development is fine by me, although there might be a word that's even clearer than "development". I thought of "unreleased" or "pre-release", but that implies that components will be moved from that state to the final state during an actual release. Perhaps it's enough to document the new infrastructure well—I think your docs in lib-development.ts are really good, and once we update the developer docs to reflect this, we could add a link to those docs in src/components-development/index.ts, since that's the file that devs will actually manipulate.

Your patches look good to me; everything is well-documented and I especially appreciate how clear it is on the docs site (locally and on the main branch) that development components are still in-progress.

Thanks! I worried that the all caps (IN DEVELOPMENT) might have been too shouty, so I'm glad you like it :)

I'm open to suggestions for better terms for sure.

What about WIP as a label for these?

We discussed this in today's meeting and settled on "work in progress" as the descriptor we prefer, with "WIP" as an acronym to be used in the directory name.

I've edited the draft ADR above to reflect our choice of "work in progress" / WIP as the term for these components.

Change 801816 merged by jenkins-bot:

[design/codex@main] build: Add separate entry point for components in development

https://gerrit.wikimedia.org/r/801816

Change 822143 merged by jenkins-bot:

[design/codex@main] docs: Flag development components, hide them in release docs

https://gerrit.wikimedia.org/r/822143

Should the "Determine how to set up test coverage thresholds for experimental components" be split into a separate task? Aside from that, this work is done and I don't think any post-merge review is needed since this is a developer-facing change.

@egardner I think that's the best path forward. I created T316139 to cover this and will close this task out. Thanks, all, for your work on this!

Change 828083 had a related patch set uploaded (by Catrope; author: Catrope):

[mediawiki/core@master] Update Codex from v0.1.0-alpha.10 to v0.1.0

https://gerrit.wikimedia.org/r/828083

Change 828083 merged by jenkins-bot:

[mediawiki/core@master] Update Codex from v0.1.0-alpha.10 to v0.1.1

https://gerrit.wikimedia.org/r/828083

Change 822144 merged by jenkins-bot:

[integration/config@master] Zuul: [design/codex] Run special doc command for release tags

https://gerrit.wikimedia.org/r/822144

Mentioned in SAL (#wikimedia-releng) [2022-10-03T13:15:58Z] <hashar> Reloaded Zuul for https://gerrit.wikimedia.org/r/c/integration/config/+/822144 # T313767

Mentioned in SAL (#wikimedia-releng) [2022-10-03T13:22:12Z] <hashar> Triggering CI for design/codex@v0.2.1 using zuul enqueue-ref --trigger gerrit --pipeline publish --project design/codex --ref refs/tags/v0.2.1 --newrev 4abb7677b3ea076bbd6778977d9a9374cf45015c # T313767

Thanks to @Catrope CI config, I have triggered the documentation generation for Codex v0.2.1. It can now be found at https://doc.wikimedia.org/codex/v0.2.1/

Then apparently the documentation was already published since there are doc for all previous tags at https://doc.wikimedia.org/codex/