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

In review/ready for review

• Writing a Good Pull Request
  • 🦘 Reviewed, added comment RE style guide
    • ❕ Responses from me and 🐙 RE RE style guide (5/1, 14:37)
    • 🐙 Reviewed, added a suggestion about one section, and tweaked some wording.
• Plugin naming convention
  • ❕ Reviewed, content looks great! (5/4, 18:06)
• Guidelines on using Blockly APIs
  • ❕ Reviewed, a few questions, but looks really good! (5/4, 18:06)

In progress

Ready to be written/Needs work

• Compatibility for plugins
  • Should work on all major browsers
  • Use browserslist section in package.json
• Welcome page
  • It's currently very empty.
• Updates to contributing.md
  • Not in the wiki, but should point more toward the wiki instead of having separate content.

Needs decisions from Blockly team

• What is a codelab?
  • Included in 'writing a codelab'
• Codelab style guide
  • Included in 'writing a codelab'
• What is an example?
• Example style guide
• First-party vs third-party plugins
  • Discussed in "adding a plugin"
• 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