Wishlist for Developer Docs

[ryanleesipes]

In Bug 1513652 on Bugzilla, Ben laid out what he would like to see documented in the docs. Below is what he said.

Also, I've been compiling a sort of wishlist for what I'd ultimately like to see in a TB development guide.

Most of the bullet points are a little arbitrary and incomplete, but hopefully it gives a flavour. I've split up into 3 main sections: "Getting Started", "Reference" and "Architecture".

Again, a lot of these things could be annotated links to existing docs, at least to begin with.

---

Getting Started

• Updated Start_Hacking guide
• Assorted "How To" guides
  • how to add a unit test
  • debugging tips
  • TB-centric Bugzilla guide
• Where to ask for help
• Relationship between M-C and C-C
• High-level architectural view

Reference

XPCOM reference

• Overview - goals, issues, common pitfalls
• Best practices/patterns/idioms
• API reference
  • Index of core platform APIs - strings, XPCOM, file access etc
  • Index of firefox APIs
  • Index of TB APIs
  • Note clearly which ones are being phased out, and their replacements
  • Docs autogenerated from code where possible, but make sure not to overwhelm with detail.
  • Curated index of important APIs
  • Ongoing effort to improve/clarify docs. If you can't easily document an API, then it's probably too complicated :-)

C++ environment

• C++-specific APIs
• Coding style
• Thread safety rules
• Linting/static analysis tools

JS environment

• JS-specific API reference (eg OS.File et al)
• preferred idioms
  • async/await vs promises vs generators
  • modules (do we have our own module system or are we moving toward some existing standard?)
• coding style
  • to run linter to check
• GUI (eg are we shifting from XUL to more HTML-based?)

Testing

• unit tests
• mozmill/mochi/whatever
• how to run/write/debug tests

Tools

• mach
• linting
• testing

Source layout

Index of stuff which is deprecated/on the way out and what replaces it. (eg using OS.File over nsIFile),

Curated index of interesting/useful blog posts/articles about TB development, with some indication of relevance/staleness.

Architecture

Concepts, intentions, aspirations. JS/C++ split - where the boundaries should be. Threading model Plugin/extension model

[Alecaddd]

I'd like to propose the addition of:

1. A Review section, as pretty much every day I discover new "must-do" in the review workflow. (eg. review coding style, check for missing new lines at the end of files, review commit message and format, etc.)
2. Handle a r+ Patch to list all the actions a developer must do after one of his patches gets a positive review (eg. push a try run, update the commit message with r=username, etc.)

[ryanleesipes]

Here are Khushil's recommendations as well:

Hello Ben,

I liked your suggestions. These are my thoughts according to your suggestions for Getting Started.

I suggest adding a link of ‘Start Hacking’ in the following page under the documentation section just below ‘Building Thunderbird’ : https://developer.mozilla.org/en-US/docs/Mozilla/Thunderbird I guess its relevant place for it. User will be able to find it easily.

• Updated Start_Hacking guide

We should make a single page and all the things that Ben has mentioned in the Getting Started :

https://wiki.mozilla.org/Thunderbird:Start_Hacking

Currently, This page is not easily available to other developers. You need to dig a bit to extract this. Need to put this page’s link such that new user can find it easily.

What exactly do we need to update here on this page? Should we add a similar page to MDN docs and update things over there? If we add more examples of JS and XUL hackings (like 2 more examples for each, one will have a good idea about it.)

• Assorted "How To" guides
  • how to add a unit test
  • debugging tips
  • TB-centric Bugzilla guide

We can include this part in above Start Hacking page with How to guides and suitable examples if possible.

• Where to ask for help
• Relationship between M-C and C-C

Ryan/Ben, can you help here? What exactly should we add in this section?

• High-level architectural view

We have High-level architectural view on Thunderbird MDN Page.(Documentation Section) : https://developer.mozilla.org/en-US/docs/Mozilla/Thunderbird. This page contains different links with a detailed overview. Some links are broken. Need to fix that. So I guess it will be fine if we are not adding it over here. After doing all the above things, the user will navigate back and explore the other present links to get a detailed overview of TB.

[Alecaddd]

I'd recommend starting a WIP PR with checkboxes representing all the suggestions and changes we want to apply, in order to have an easier and more organized way to track this list.

[ryanleesipes]

Hey @Alecaddd I have moved many of these things to the Projects tab. I'm not opposed to a WIP PR with this stuff, but I'll need to catch up with you to understand why that would better versus some other approach. In the meantime if anyone wants to help me decide what has been done vs what needs to be done vs what can be thrown away in the projects tab - I would much appreciate that.