Closed possumbilities closed 3 months ago
These two items:
.github/CODEOWNERS
(probably @creativecommons/internal-tech
)From a comment by Timid Robot : [Request]: Push access to various Vocabulary related repositories for Sara Lovell creativecommons/vocabulary#941 (comment)
Need to be incorporated into the above Issue where relevant.
Much has changed since this was originally drafted. Closing this as out of date. Will create a new Issue and link below with accurate information.
Notice: This Roadmap was originally created with the Vocabulary Legacy codebase as a reference point. Since then, much has changed, including the archiving of that repository to
cc-archive/vocabulary-legacy
. This Issue remains here for history and referencing, but is no longer considered fully current and accurate.Notice: As there is still much to discover, this Roadmap is considered a
work in progress
and is still subject to change.TOC
Summary
Vocabulary has become sprawling, out of date, difficult to maintain, mismatched in documentation, and overly complex. It needs to be reconsidered from multiple angles, and given clarity not just in structure, but also approach.
Goals
Outcomes (proposed)
Code
creativecommons/vocabulary
o--o@creativecommons/vocabulary
creativecommons/vocabulary-vue
o--o@creativecommons/vocabulary-vue
Project Structure / Mechanics as a Design System
Why?
Most of the issues with Vocabulary sit within two categories:
The intended original scale and scope of Vocabulary has shifted dramatically since its original creation, creating conflicting objectives and philosophies.
In many current situations code implementations don't necessarily need a node package to implement Vocabulary, they just need a link to a relevant
vocabulary.css
file hosted on a CDN, and a reference spec for how markup should be output and what adjacent behaviors it should follow.More complex setups just need a straight-forward Vue Components library that has Vocabulary itself as a dependency.
From a repository standpoint, Vocabulary started as separate repositories, then became a monorepo, and then back to separate repositories in some instances--and the original monorepo in others.
This project seeks to move the core of Vocabulary back to a singular repository, and keep the Vocabulary Vue Components implementation as its own repository. There is insufficient documentation for why Vocabulary was split in precisely the ways it was originally, but some of its difficulty in being maintained either as separate repositories or as a monorepo is in how the project is structured overall. The newly proposed structure seeks to address these issues.
The Current Challenges section does a good job of elaborating further.
History
Note: The
creativecommons/cc-assets
repository and package are included here for completeness, but they were never fully integrated into the Vocabulary project.Vocabulary Multi-Repo 2019-2020
Repositories and JavaScript Packages
creativecommons/cc-assets
@creativecommons/cc-assets
creativecommons/fonts
@creativecommons/fonts
creativecommons/vocabulary
@creativecommons/vocabulary
creativecommons/vue-vocabulary
@creativecommons/vue-vocabulary
Vocabulary Monorepo 2020-2022
[RFC] Move vocabulary packages to a monorepo · Issue creativecommons/vocabulary#612
Dedicated repositories archived
creativecommons/fonts
cc-archive/fonts
creativecommons/vue-vocabulary
cc-archive/vue-vocabulary
Repositories and JavaScript Packages
creativecommons
Repocc-assets
@creativecommons/cc-assets
vocabulary
./packages/fonts
./packages/vocabulary
./packages/vue-vocabulary
@creativecommons/fonts
@creativecommons/vocabulary
@creativecommons/vue-vocabulary
Vocabulary Incomplete Re-Split 2022
Split Vocabulary packages into separate projects · Issue creativecommons/vocabulary#1049
Repository directories migrated to new repositories
./packages/fonts
creativecommons/vocabulary-fonts
./packages/vocabulary
creativecommons/vocabulary-styles
./packages/vue-vocabulary
creativecommons/vocabulary-components
Repositories and JavaScript Packages
Due to the incomplete re-split, all of the packages remain in use:
creativecommons
Repocc-assets
@creativecommons/cc-assets
vocabulary
./packages/fonts
./packages/vocabulary
./packages/vue-vocabulary
@creativecommons/fonts
@creativecommons/vocabulary
@creativecommons/vue-vocabulary
vocabulary-components
@creativecommons/vocabulary-components
vocabulary-fonts
@creativecommons/vocabulary-fonts
vocabulary-styles
@creativecommons/vocabulary-styles
Current challenges
Code Rot / Sprawl / Complexity / Performance
fonts
exist as a package of their own, when there is zero known use for them to be implemented without vocabulary itself.vocabulary styles
follow the same practice asfonts
. (In some casesvocabulary-styles
was the originalvocabulary
repo).bulma.js
adds a further layer of abstraction that doesn't actually normalize, but instead resets the default behavior of elements.storybook
is useful, but also complex. It needs to be reproached with more clarity, or replaced.Change in Objective / Scope
Node (NPM) as a CDN Pipeline to unpkg
Originally, Vocabulary was built as a robust design system to be used from an application-centric focus. This meant that there were certain challenges when implementing it within setups such as WordPress, since the main core focus was from compatibility with the Node System, and more specifically with Vue.js.
Since then, the focus of Vocabulary use-cases are much more WordPress / Static site centric, with app uses as the secondary priority.
In this way, currently, NPM's major function, and by proxy these repositories existing as Node packages, is to publish them easily to a CDN (unpkg), not to necessarily be consumed as as dependency in Node projects. Individual files (primarily the font and css files) are then often used as
<link>
includes in relevant codebases.This isn't entirely untenable, but there are likely alternative CDN solutions for this use-case that don't primarily rely on the NPM ecosystem or on unpkg.
Source of truth and conflicting design system mechanics
From the Storybook documentation:
A design system that's primarily used within code, needs its
source of truth
to be actual code, and more specifically themeaning
andpresentation
, and oftenbehavior
of various design elements. A program like Figma can somewhat provide the presentation part of the source of truth, but as it is more visually focused it is unreliable for the actual code (CSS) implementation of that presentation, and even less so for the meaning, which is mostly derived from the HTML markup. As for behavior, the results can largely be mixed from relying on Figma. This means resting the source of truth on Figma results in the presentation being incomplete, the behavior being inconsistent, and the meaning having to be derived elsewhere.As a result, coming from an app-centric focus, the Vue.js Components and Vocabulary Styles ended up being closer to the actual original "source of truth" for meaning + some behavior + presentation, and this meant that Vue and by proxy Node conventions set the tone and direction of how and where Vocabulary could/should be used. This likely made solid sense considering the original focus and the original use of Vue.js in a larger application-centric approach.
This doesn't make as much stable sense in the present, where WordPress themes largely need a CSS file of appropriate styles, and a directed documented implementation guide for how the markup should be output. The most direct implementation being as Gutenberg blocks on the b/e and as PHP code for the f/e rendering
There is also the possibility of the WordPress theme utilizing Vue.js Components into the mix, which paired with the backend editor (Gutenberg) being in React.js may introduce unnecessary complexity.
The Vue.js components have a use, but they should be an implementation of
a source of truth
not the originalsource of truth
. The current configuration leans too heavily on the latter.Change in scale
At greater scale (multiple apps, higher number of engineers + teams) high reliability on a f/e framework (Vue.js, React.js, etc.) as the majority source of truth for components can be worth any complexities or missing pillars that come along because they help to not just enforce a Component, but to enforce that component's markup in a more direct, but also abstract pathway.
When the scale is not quite as large, these tradeoffs can come at a much higher cost. Additionally, if in the future there is a need to pivot away from utilizing a specific framework as the source of truth, then the migration path can be challenging since there is no framework agnostic source of truth to go back to as reference.
In general, if the project isn't going to have the kind of scale of a larger SAAS/PAAS company, it can make more sense for a Design System to first exist as a singular source of truth of components in as native of a format as possible (HTML, CSS, helper JS). There is some documentation of this within
storybook
, but it is inconsistent, some of the markup relying only on Vue markup.Then, you can have various implementations in frameworks as they become relevant (Vue.js, React.js, etc.). This provides a stable source of truth that will remain relevant regardless of needed implementation. Changes to core Vocabulary can then cascade down to the individualistic implementations with their own specific nuances.
There are many sound reasons to pick one approach over another, or to pursue additional routes. However, much has changed since the original creation of Vocabulary, most importantly its use requirements, which include its scale. This has resulted in a high degree of complexity and code rot, which stands in the way of stable maintainability and accurate documentation.
Incomplete Documentation
Objectives (work in progress)
Setup
creativecommons/vocabulary
vocabulary-2022.Q1-hybrid
creativecommons/vocabulary
creativecommons/cc-assets
creativecommons/vocabulary-components
creativecommons/vocabulary-fonts
creativecommons/vocabulary-styles
creativecommons/creativecommons-certificate
creativecommons/wp-theme-openglam
creativecommons/creativecommons.github.io-source
creativecommons/wp-theme-summit
creativecommons/cc-global-components
creativecommons/cc-legal-tools-data
creativecommons/cc-legal-tools-app
creativecommons/creativecommons-base
creativecommons/chooser
Phase 1
Involves the
creativecommons/vocabulary
repository once again becoming the central hub of work, after several repositories have been combined, their functionality and associated NPM packages will be updated to reflect those changes, followed by changes with any projects which utilize those repositories as a dependency in some way.1.1 Setup -
creativecommons/vocabulary
1.2 Return a stable set of src files to work from -
creativecommons/vocabulary
/src
by moving to/src/_deprecated/
for later referencecreativecommons/vocabulary-styles
repo./src/scss/
directory/src/fonts/
directory/src/scss/vendor/
to be more hermetic in builds and set foundation to deprecate later1.3 Make a versioning decision -
creativecommons/vocabulary
semver
vscalver
: answer:semver
1.4 Node cleanup -
creativecommons/vocabulary
package.json
andpackage-lock.json
files removing dependenciespackage.json
file meta data@creativecommons/vocabulary
namespacevocabulary
namespace, what is the alternative?@creativecommons/vocabulary-core
1.5 Prepare and move forward with pre-release -
creativecommons/vocabulary
/dist/css
directory to house thevocabulary.css
andvocabulary.css.map
files going forwardvocabulary.css
file in/dist/css/
⚡ [milestone] - stable MVP foundation reconstructed with as much git history intact across relevant repositories.
1.6 Publish 2.0.0-alpha pre-release -
creativecommons/vocabulary
@creativecommons/vocabulary-core
~1.7 Ensure repo follows current Repo Guidelines -
creativecommons/vocabulary
/.github/CODEOWNERS
/.cc-metadata.yml
/CODE_OF_CONDUCT.md
/LICENSE
/CONTRIBUTING.md
/README.md
1.8 Make determination on remaining repos
cc-assets
as standalone repocreativecommons/vocabulary-fonts
-->creativecommons/cc-fonts
creativecommons/vocabulary-styles
now that relevant code is merged intocreativecommons/vocabulary
creativecommons/vocabulary-components
; rename, new repo, archive1.9 +
[After several weeks of archaeology the original roadmap proposed for Phase 1 needs further consideration and updates on the best route forward.]
Phase 2 CDN Reconsideration
Vocabulary should not rely on being primarily a node package published to and served via npm/unpkg. This can remain secondarily, especially for node ecosystem specific projects, but for any other use cases that just need a
<link>
reference to utilize vocabulary there are better approaches, namely a simplistic CDN deployment pipeline that is not unpkg.vocabulary.css
--> [custom cdn]vocabulary.js
--> [custom cdn]Phase 3 - Refactor Vocabulary to be proper source of truth
Much of the work thus far has mostly been to get the repositories reduced, clarify the code, and make the CDN setup more robust. However, Vocabulary itself still needs the bulk of its code to be refactored. There is a strong likelihood that bulma needs to be removed/replaced, and that storybook needs a reconsideration.
creativecommons/vocabulary
--> [refactor transforms as proper design system hub, remove bulma]creativecommons/vocabulary
--> [refactor builds css + js files] --> outputs to non unpkg CDNcreativecommons/vocabulary-vue
--> [refactor with vocabulary dependency, matching new spec}creativecommons/vocabulary
--> [rewrite Storybook (or equivalent) to be new system explorer]Future Considerations
creativecommons/vocabulary-web-components
--> [new repo?]creativecommons/vocabulary-react
--> [new repo?]creativecommons/vocabulary
vocabulary-web-components.js
--> [custom cdn?]Unknowns (WIP)
The use of
storybook
as a documentation/site tool may need to be replaced or possibly just changed in structure or use, but not enough is known to make a solid callTests have suffered from issues dealing with mostly time and code rot, the shifting scope of Vocabulary also impacts the expected outcomes of various functionality, as well as the possibility of changing up tooling. Which means Tests overall are in some instances intentionally disabled, in others broken from the side effects of time, and will likely need a revisit as things shift within Vocabulary's new scope. All this to stay, knowing exactly what to do with tests is going to be messy. They may need to be taken out entirely, and then reconsidered in a full refactor.
It would be handy to run tests through something like Browserstack, no idea just yet if an equivalent exists in the current setup, or if there's solid reason to do so down the line
Establishing the correct versioning scheme to follow going forward (semver vs calver). Using calver with the two digit month breaks on npm/unpkg as it removes the extraneous 0 to be compatible with semver (which it expects). To account for this, and still use calver means dropping the extraneous 0 on all js projects, but then across the board versioning in some projects has the zero and in others does not, creating inconsistency
The
creativecommons/cc-assets
repository has items licensed under the Creative Commons Trademark policy, bundling them in with another repo will require someLICENSE
language delineating that they are not necessarily licensed the same as the rest of the repo or its assets.creativecommons/cc-assets
are included within thecreativecommons/vocabulary
repo already, but there is no delineation made about licensing in Vocabulary'sLICENSE
file, or itsREADME.md
file in regards to those items.Related Resources
Wikimedia Style Guide
Wikimedia Style Guide (on GitHub)
Polaris by Shopify
Polaris on GitHub
VuePress
GitHub Pages
Twitter Bootstrap