Reducing Maintenance Burden
Reducing Maintenance Burden
I think we all did a great job at pulling various pieces of code samples and docs together as they came available into the dev site. It's an appropriate time now after the Tech Preview launch to do some tech and process debt payoff. @dayhaysoos-tbd and I talked through one pain point in particular - the amount of work necessary to do a Web5 upgrade. As we proceed, this is only going to become a bigger problem the more docs we introduce - for Web5, for SSI, etc.
So here's our thinking about slimming that process. It's in 4 Phases:
1️⃣ Unify all docs on developer.tbd.website to respect one dependency - a Bill of Materials.
This will give us a single place to update, for instance, a Web5 or SSI dependency. All downstream efforts with the Web5 dependency: TODO App Guide, TODO app starter template, TODO app finished example, Quickstart, Quickstart
index.js
, Quickstart front-end widget - respect and use that one declared dependency. This gives us one place to update across the entire docs suite - no more cascading updates in several places and issuing new releases across different repos.
2️⃣ Introduce Comprehensive Automated Test Suite
Right now all our QA is manual - and runtime. We will introduce a comprehensive test suite for all runnable code. It'll come with a few layers likely - standard tests that the flows are working, and browser-driven ones that validate the UI (using Selenium or similar).
This gives us confidence in upgrades. When we upgrade the single Bill of Materials for a new Web5 release - the testsuite will let us know if everything is good to go, or if we need to make changes. It also gives the Web5 team a great acceptance test if we catch anything in the internals that we've broken.111 Replies
3️⃣ Inject tested code into written docs
A long-standing topic that goes back a year and has even been prototyped by @frankhinek. The idea here is that once we have tested codebases in our examples, we pull exactly that code and inject that code into the docs.
This means that 1) The docs will always show the right thing and reduces our dev error in reflecting changes and 2) @bobbilee_tbd for instance will not need to update the code sections of the written docs to match the example code: they'll simply be pulled into the docs and inlined.
4️⃣ Automate wherever possible
With GitHub Actions and similar, we can trigger an upgrade to the Bill of Materials whenever OSE wants to propose an upstream component like Web5 or SSI for release. That automated flow can make a branch for us, do the upgrade in the BOM, run the tests, and show a deploy preview. We can further make the manual changes we need on that branch should anything in the upgrade require docs changes.
I believe this combination of approaches is going to reduce our overhead in upgrade and limit our introduction of bugs, making for smoother delivery and more guaranteed developer experience.
This is the primary focus of the Programs team right now. @dayhaysoos-tbd DRIing solutions around these guiding principles and we'll track these 4 in GitHub; he may break them off into subtasks.
Thoughts encouraged before we put these into action!
Unknown User•2y ago
Message Not Public
Sign In & Join Server To View
@dayhaysoos-tbd Digging into an RFC to run by stakeholders on Step 1.
https://github.com/TBD54566975/developer.tbd.website/issues/533
GitHub
Reduce Maintenance Overhead · Issue #533 · TBD54566975/developer.tb...
Umbrella issue for work related to making Web5 (and other projects) upgrades on the Developer Site simpler. From Discord thread: #532 Step 2 - Introduce Comprehensive Automated Test Suite (issue to...
Unknown User•2y ago
Message Not Public
Sign In & Join Server To View
Liked Nick's last update - I've got an updated review in there and think we should sync to make decisions 🙂 @bobbilee_tbd @dayhaysoos-tbd
Unknown User•2y ago
Message Not Public
Sign In & Join Server To View
Fantastic - best way to find out is to do it! Thanks @bobbilee_tbd and @dayhaysoos-tbd!
Unknown User•2y ago
Message Not Public
Sign In & Join Server To View
Might be worth messaging to folks this is happening as it's a structural change:
git mv
on every asset. Quicker we can get that in there the better in my experience; new PRs will all make conflicts in the interim. 🙂
Like even as a first step: move the entire repo contents under a site
folder first. If we get that commit in and adjust Netlify, then the rest of it is just incremental and non-conflicting.Unknown User•2y ago
Message Not Public
Sign In & Join Server To View
Sure, and hear my point about just the simple lift and shift of burying the full site contents under one
site
folder? It kind of frees you up to make all those changes without conflicts.Unknown User•2y ago
Message Not Public
Sign In & Join Server To View
Dope
Go crush it
Unknown User•17mo ago
Message Not Public
Sign In & Join Server To View
No need to hold things up if:
https://discord.com/channels/937858703112155166/1111754777307660388/1119018151871512677
^ If that commit goes to main then all site contents move and everyone can continue working in parallel 🙂
Unknown User•17mo ago
Message Not Public
Sign In & Join Server To View
Sweet I’ll have a look today. But don’t hold on it - you and Bobbilee worked through it and made a plan so you’ve got it
Unknown User•17mo ago
Message Not Public
Sign In & Join Server To View
Lemme know if you wanna pair up - I'm free in 15min
Unknown User•17mo ago
Message Not Public
Sign In & Join Server To View
Fantastic plan that makes less conflicts and lets work continue in parallel through end of week on the
pnpm
stuff and the Docusaurus error - thanks Nick!Unknown User•17mo ago
Message Not Public
Sign In & Join Server To View
Shouldn't - Nick ran a test on it locally and thought best to signal to folks the structural change is happening before pushing to
main
Unknown User•17mo ago
Message Not Public
Sign In & Join Server To View
Nick you found it!
Unknown User•17mo ago
Message Not Public
Sign In & Join Server To View
This thread is a wild ride
I’ll look to see if Netlify has a setting to always clear cache. IME every build should be totally clean, no persistent history
@dayhaysoos-tbd For tomorrow - how do you feel about our running an
rm -rf
on the cache directory as part of the build commands?
https://answers.netlify.com/t/how-to-clear-cache-on-branch-deploy/5521/3Unknown User•17mo ago
Message Not Public
Sign In & Join Server To View
@dayhaysoos-tbd Last branch I saw you were working on was
prototype-monorepo
; where's the lastest you'd like someone to run through above?Unknown User•17mo ago
Message Not Public
Sign In & Join Server To View
Ah sweet thx
@dayhaysoos-tbd It downloads both Web
0.7.8
and 0.7.9
?
Unknown User•17mo ago
Message Not Public
Sign In & Join Server To View
Looks great so far! I’ve some things here - so can do a more thorough PR review for Monday
Else if you’re feeling good and the DevRel team can validate it works for them to continue issuing updates - no blockers from me
Unknown User•17mo ago
Message Not Public
Sign In & Join Server To View
Me too. My mantra is incremental improvement - so long as it’s not a step back or breaks DevRel workflow, let’s keep it Comin!
Monday let’s review to acceptance check w DevRel - nice job this week especially with finding how to adapt Docusaurus to respect pnpm 🤘🏻
Unknown User•17mo ago
Message Not Public
Sign In & Join Server To View
@dayhaysoos-tbd I can 1pm your time
Unknown User•17mo ago
Message Not Public
Sign In & Join Server To View
@dayhaysoos-tbd And I ran through the PR and its implications. Result of that review is here: https://github.com/TBD54566975/developer.tbd.website/pull/564#pullrequestreview-1499117695
Impact of this for DevRel team should be, by its end:
* Single place to declare dependencies on Web5, cascading to all elements of the site and its examples/tutorials
* Same commands to build and deploy, replacing
npm
commands with pnpm
* Much more clear naming for what was incubating-web5 labs
and web5-tutorials
into examples/$appName/$appName-starter
and examples/$appName/$appName-completed
.Unknown User•17mo ago
Message Not Public
Sign In & Join Server To View
The naming differentiation like Angie is suggesting IMO makes things much clearer
We really wanted to mail that in Austin and I don’t think ever landed on the definitions of example, demo, tutorial, playground, etc. This is a great opportunity to prove those out through this folder structure.
@dayhaysoos-tbd, can we pair a day this week? maybe Thurs? I can send you a calendar invite
Unknown User•17mo ago
Message Not Public
Sign In & Join Server To View
sent 🤗
Added latest PR review based on my pairing w/ @dayhaysoos-tbd today - he's cranking and each day we're checking in and talking through how this gets ever cleaner and easier:
https://github.com/TBD54566975/developer.tbd.website/pull/564#pullrequestreview-1499117695
@bobbilee_tbd In that above link there's an open Q to you about the completed
index.js
in the Quickstart - I think it makes a lot of sense; looking to you to confirm we're not missing anything?
Hey @dayhaysoos-tbd - you mentioned that the pnpm
work also laid bare a dependency mess you were able to clean up a lot, and it removed a bunch of issues.
On main
now if I run npm install
we get:
Were you saying the pnpm
work and cleanup resolves these vulns?Unknown User•17mo ago
Message Not Public
Sign In & Join Server To View
Looks like @dayhaysoos-tbd is aiming to land this by end of week, starting on test infra for QuickStart and TODO app next week. All I’m seeing is working nicely, and there’s a hitlist of docs and organizational tasks in the PR he’s working through before bringing this to a close
@bobbilee_tbd is principal stakeholder here and she’s been running through the branch, doing acceptance testing and feedback 🤘🏻
Unknown User•17mo ago
Message Not Public
Sign In & Join Server To View
Yah the
pnpm
infra is looking great and I really see how this is going to help with upgrades - not to mention paving the path for tests across the whole suite.
The content impact is something I agree it'd be great to review w/ @bobbilee_tbd - making sure that the new ways devs get the starters and completed examples fit DevRel specs.
The histlist for those docs changes to take advantage of Nick's restructuring is here: https://github.com/TBD54566975/developer.tbd.website/pull/564#issuecomment-1615117459Unknown User•16mo ago
Message Not Public
Sign In & Join Server To View
It’s a bundling issue and using Web5 w Jest, the test framework. @dayhaysoos-tbd can elaborate tomorrow 🙂
Unknown User•16mo ago
Message Not Public
Sign In & Join Server To View
@dayhaysoos-tbd You can prob push into your own fork too if you’re looking to share stuff on its way to a PR into Bonanza 🤘🏻
Super cool to see ya addressing it at this level, and props to you @adalundhe!
Unknown User•16mo ago
Message Not Public
Sign In & Join Server To View
Hi! Appreciate all this! Quick note that @dayhaysoos-tbd is out today and he’s best to pair with ya on this stuff!
Unknown User•16mo ago
Message Not Public
Sign In & Join Server To View
You love to see it. ✅ on tests always gives me that dopamine 🤘🏻
Unknown User•16mo ago
Message Not Public
Sign In & Join Server To View
I’m so amped about this
Unknown User•16mo ago
Message Not Public
Sign In & Join Server To View
Yah that’s awesome - even right there you’ve got both the site and some examples running in one go
Unknown User•16mo ago
Message Not Public
Sign In & Join Server To View
Yeah the tests you’re writing now kind of pave the path for how we check postconditions on Web5 operations, agree it’d be good to get Web5 team eyes on it to check those postconditions are right
Unknown User•16mo ago
Message Not Public
Sign In & Join Server To View
Or ask in the #web5 channel! @dayhaysoos-tbd I bet you might be able to get some guidance there with a couple Qs async
Unknown User•16mo ago
Message Not Public
Sign In & Join Server To View
Let’s rubber duck 🙂
The cool thing about being a software engineer is that if you’re looking at working code you’re not really working 🤣
Unknown User•16mo ago
Message Not Public
Sign In & Join Server To View
Yup that makes a lot of sense to me - crux of the issues sound like bundling, something I hear echoed from @moegrammer and some others on the team 🙂
Moving to some of the less complex examples for testing and working w/ the dependency, bundling, w/ the team sounds super appropriate
Unknown User•16mo ago
Message Not Public
Sign In & Join Server To View
This is so cool @dayhaysoos-tbd, running from the root:
Unknown User•16mo ago
Message Not Public
Sign In & Join Server To View
Early on in Arquillian the message we had for talks was: "Get that green light!" Like it was all about the dopamine of seeing tests passing, the joy of writing more tests.
This is def a joy to see. Can't wait to build out this suite.
Unknown User•16mo ago
Message Not Public
Sign In & Join Server To View
Just had a good call w/ @dayhaysoos-tbd on the testing progress - raising here for folks to see the inventory of stuff he's got in his sights for end of week:
Quickstart:
✅ Embedded Quickstart in
site
⬜️ The existing index.js
(https://developer.tbd.website/assets/files/index-09e4d0130f1c7df9f3bd1f6bc5049589.txt) becomes a Node project in examples
⬜️ The HTML Frontend Widget (https://moonlit-centaur-0d7b4f.netlify.app/) moves to examples
(https://github.com/TBD54566975/developer.tbd.website/tree/main/examples/web5-quickstart-widgets)
TODO App:
⬜️ Completed TODO App (https://unrivaled-crumble-56ce70.netlify.app/) in Vue moves to examples
(https://github.com/TBD54566975/developer.tbd.website/tree/main/examples/tutorials/todo-completed)
When done, these 4 suites will complete testing of existing examples as outlined in step 2️⃣ at the beginning of this thread 🤘🏻
Sets us up to bring in more and follow the same patterns everyone's been working so hard to get tested in various environments w/ bundling etc.Unknown User•16mo ago
Message Not Public
Sign In & Join Server To View
@dayhaysoos-tbd So Imma run through the latest on
main
like we discussed. 🙂 Should I be seeing this?
Unknown User•16mo ago
Message Not Public
Sign In & Join Server To View
Yup
The run is also blocking on file changes, not continuing on to other workspaces
Unknown User•16mo ago
Message Not Public
Sign In & Join Server To View
Ah interesting, it's different but still blocking the 2nd time:
And even different a 3rd time:
Unknown User•16mo ago
Message Not Public
Sign In & Join Server To View
Terminal blocking on input, not proceeding past the test run while it waits for file changes - see the end prompt where it hangs
Unknown User•16mo ago
Message Not Public
Sign In & Join Server To View
Yep it's not so much failing here as hanging. Recommend setting up Netlify authoritative build to run the tests as part of the build process; that will give us clear indications moving forward about what's working and not in our branch deploys.
Unknown User•16mo ago
Message Not Public
Sign In & Join Server To View
Yes, but Netlify doesn't run
pnpm test
, only npm run build
Unknown User•16mo ago
Message Not Public
Sign In & Join Server To View
Right, that's also still blocking; how do you proceed to the next stage of the build?
Unknown User•16mo ago
Message Not Public
Sign In & Join Server To View
I'm expecting:
pnpm test
to build and run all the tests in the monorepo, and report results, no?Unknown User•16mo ago
Message Not Public
Sign In & Join Server To View
I can #tbd-stage to work through it in 30min, or next week if you're at the end of your Friday
Unknown User•16mo ago
Message Not Public
Sign In & Join Server To View
But Netlify looks like it's not set to run tests, or use
pnpm
at all?Unknown User•16mo ago
Message Not Public
Sign In & Join Server To View
Sure, the command can be whatever makes the most sense, but in the authoritative build on Netlify, it's not dev mode. So the command can't "block" on user input to proceed after running tests
Unknown User•16mo ago
Message Not Public
Sign In & Join Server To View
OK. Short term I think we should figure a solution for that and make sure the Netlify config is running everything it needs to, to catch errors for us. I think it's outdated; still on
npm run build
now.Unknown User•16mo ago
Message Not Public
Sign In & Join Server To View
Available if you're working! Else catch ya Monday.
Unknown User•16mo ago
Message Not Public
Sign In & Join Server To View
@dayhaysoos-tbd just merged a PR to enable GH Actions to do test runs on
developer.tbd.website
@dayhaysoos-tbd - Does that mean branch deploys will just come back, or is that something we've gotta put back into the Netlify config? Some PRs in play we can clear up once the CI there is up and running againUnknown User•15mo ago
Message Not Public
Sign In & Join Server To View
Ah cool so maybe we can manually trigger them?
Unknown User•15mo ago
Message Not Public
Sign In & Join Server To View
Hmm, kind of interesting now, because our tests run on GitHub Actions while the Netlify build runs obi on Netlify...so maybe it's: trigger build hook from GitHub console?
Like the Netlify Deploy Preview isn't the whole story; manually triggering that bypasses the GH Actions suite
Unknown User•15mo ago
Message Not Public
Sign In & Join Server To View
Yah or we can, for PRs on branches in
upstream
, simply rebase them atop main
and force push those changes to the PR so the jobs re-run, and we can check that way. How do you wanna handle, @dayhaysoos-tbd ?Unknown User•15mo ago
Message Not Public
Sign In & Join Server To View
Cool