Technical Maintenance Documentation

[twblack88]

[Portal] Technical Maintenance Archive

Hello! If you're new to our "Archive" section, here's a tag explainer:

While Community Development's programs supported by Maker Foundation comes to an end, the "Archives" issues provide insight to project/programs that the team had worked on. Anyone could apply the lessons learned in community development, harvest timeless content, and deploy the stack somewhere else.

Motivation

In order to keep up with a dynamic ecosystem, the technology underpinning the content in the portal needs to be maintained. We have a simple git based workflow that is robust enough to tell you if you break something.

Summary

Maintenance is simple: make sure the website doesn't break, and keep assisting content creators with improving the portal's pages.

More granularly that means assisting with git and branch management, updating plugins, fixing blockers with local development, answering workflow questions, making sure the checks function and don't throw weird errors, and being attentive to details along the way. Our philosophy is "content creators write the website." So, any requests come from them, since they are writing for the wider MakerDAO community. This repo leverages github pages for deploys, and local development for consistency.

Role(s)

• Github Admin(s)
  • Merge PR's and clarify any failed checks
  • Check YAML frontmatter for conflicts (UI problems on mobile, misplaced components etc.).
• Lead engineer
  • Build out supporting code and architecture changes.
  • Keep an eye on open source updates that might mess with build process.
  • Help n00bs with git flow and branch protections.
• Content creator(s)
  • Update pages that become out of date with protocol changes merging in governance updates (modules and parameters)

Nice to have roles

• Supporting engineer
  • Extra coverage for any mis-merged code
  • Global coverage (if they are in Europe or Asia)
• Designer
  • Making sure each page is consistent. This is still a problem with the portal at the moment.

Related Links

• Portal tag on github
• Repo for technical development
• Content maintenance archive

Basic needs

• A team of people that meets cross functionally with facilitators in Maker Governance and other teams that need canonical information displayed (until a new site takes over that function).
  • Some level of content creation: pages for governance or pages on the community blog.
• One admin who merges changes on Thursdays or Fridays every week.
  • (Checking for any out of place styles, making sure the build runs, and keeping the branches clean)
• An engineer to call on if things break or get funky.

Nice to have

• Active maintenance sprints. Previously we would do these quarterly, and it's is too long to keep the team aligned around using git and pushing pages. Github is a tool you should use almost everyday a little bit to stay fresh. In addition, the technical architecture of the portal is so modular that you can iterate on lots of pages and pick the best ones.

---

Reach out to Tim on twitter or github (@twblack88) for additional questions or if you hit a snag with getting the stack working.

Extra

TL ; DR High-level Workflow:

• Follow the installation guide
  • get local setup functioning on a local branch yarn and yarn start should work.
  • open the palette page
  • Get a new .mdx page working via yarn
  • Merge master and r2d locally
  • Build to see changes hotloading
  • Commit changes
  • push to origin when satisfied with work
  • Open to review by one other reviewer
  • Fix anything caught in review
  • Merge to master/r2d
  • Push to production
  • Double check the build passes