Wiki planning

This page is meant to help plan how the wiki will be set up and organized. It is not meant to stick around forever, but be around temporarily until a minimum viable wiki is completed.

Process for writing pages

Draft->needs review->draft->needs review->published

For draft pages, put an "under construction" section in at the top (:warning: :construction: This page is under construction! :construction: :warning:) and use a horizontal rule to separate it from the rest of the page. You can also add comments there on what needs work.

For needs review pages, put a "needs review" section in at the top (:interrobang: Needs review :interrobang:)and use a horizontal rule to separate it from the rest of the page. You can also add comments there on what needs review.

For broader discussion, add a horizontal rule and a "Talk" header under the main content of the page.

We will likely need more process but this is a start.

Page Status

Published

(These pages may still be edited, but are ready for general consumption.)

• Plugin Publishing
  • ❕ reviewed
  • 🦘 reviewed
• Finding a Good Issue: Labels
  • 🐙 reviewed
  • 🦘 reviewed
• How to Write a Good Issue
  • 🐙 reviewed
  • 🦘 reviewed
• Repository Structure
  • ❕ reviewed
  • 🦘 reviewed
• Adding a Plugin
  • ❕ reviewed
  • 🦘 reviewed
• Writing a Codelab
  • ❕ reviewed
• The PR Review Process
  • 🐙 reviewed
• Plugin naming convention
  • ❕ Reviewed, content looks great! (5/4, 18:06)
  • 🐙 Comment re: formatting: I tried going down to three columns but I think this actually has all the right information, and I like the tables for the parallel structure, so I'm going leave the formatting as-is.
• Writing a Good Pull Request
  • 🐙 reviewed, and condensed the style guide section to point to the three links we have available.
• Guidelines on using Blockly APIs
  • ❕ Reviewed

In review/ready for review

• Welcome page
• Updates to contributing.md

In progress

Ready to be written/Needs work

• Compatibility for plugins
  • Should work on all major browsers
  • Use browserslist section in package.json

Needs decisions from Blockly team

• What is an example?
• Example style guide
• How to write and run tests for plugins
• Style guide for plugins

Research

Contributing

• https://github.com/toggl/toggl-button/blob/master/.github/CONTRIBUTING.md and https://github.com/toggl/toggl-button/wiki/Adding-new-integrations
  • I think this may be good resources because the toggl-button repo is also essentially a collection of plugins.
  • The difference is they're pretty much like "all commers are welcome!" where this repo wants to be a little more selective.
  • I like how the tutorial walks you through all the steps for creating a new integration. I'm not sure if that's necessary, or even possible given how different plugins here may be. But I do think it's interesting that it worked for them.
• https://docs.readthedocs.io/en/stable/contribute.html
  • They're Contributing to Developement section is very friendly and to-the-point.
  • They're issue triage documentation is also clear and helpful.
  • I like how they reference contribution-guide.org.
• https://github.com/microsoft/calculator/blob/master/CONTRIBUTING.md
  • I feel like this one is a bit boring, it doesn't make me want to contribute.
  • It does include lots of the important information I need though: where to find issues, how to get started, what the PR process will be like.
• https://www.writethedocs.org/guide/contributing/
  • This definitely has a tone that I like, but it feels a little bit disorganized.
  • When reading this I wonder: where is your repo? how do I find stuff to work on? I don't feel like I'm ready to contribute.
• https://github.com/atom/atom/blob/master/CONTRIBUTING.md
  • I think this guide is really good and thorough!
  • I don't appreciate how much detail they go into about submitting issues. I feel like your issue template should contain all the info a person needs to submit one. If it doesn't, you might be asking a bit much.
  • I'm am not in favor of fancy commit messages. I think that people should focus on writing a good PR rather than spending time on long commit messages. But I could be wrong here.
• https://github.com/rails/rails/blob/master/CONTRIBUTING.md
  • I am personally not a fan of this guide. The bolded questions about "did you already do x" seem a bit abbrasive.
  • I think that they may have gone a bit bullet happy. I know... I'm writing a giant bullet-list right now, but this is for planning, not trying to welcome new peeps. I feel like having everything be a bullet made reading it feel abrupt.
  • 🐙 I agree, this one is much less friendly. Not the tone that we want to strike. --Rachel

Talk

🐙 is Rachel

❕ and ❔ are Beka

🦘 is Sam