1513652 - Updated Developer Guide for Thunderbird

Status: RESOLVED FIXED

(Thunderbird :: Help Documentation, enhancement)

Description

[Ryan Lee Sipes]

For onboarding purposes we need a maintained developer guide to help onboard folks to making contributions the Thunderbird. Was going to link to: https://wiki.mozilla.org/Thunderbird:Start_Hacking - but it appears to be outdated/not useful.

Comment 1

[Ben Campbell]

(going a little beyond the start-hacking guide here, but it seems as good a place as any :-)

I'm still pretty new and getting to grips with TB development, so here's my take on documentation:

There's a load of documentation out there, but it's not always clear if it's up-to-date or how relevant it is.
Some of it is deprecated in firefox, but still relevant to TB. Some stuff is relevant, but too firefox-specific.
I tend to find docs via search, so I'll often end up with docs that seem relevant, but I'm uncertain how they fit in to the bigger picture.

For me, a good starting point would be to have a nice curated (and maintained) index of TB-relevant links - just a page or two - linking out to existing resources.
These links could be annotated with TB-relevant information.
- links to overly firefox-specific docs could have a note to say which aspects are relevant to TB
- deprecated documentation should be marked as such (eg a link to a deprecated API should have a note to indicate what the preferred replacement is).

This could then be fleshed out with more TB-centric docs and guides as we go along.

Comment 2

[Ben Campbell]

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

Comment 3

[Ryan Lee Sipes]

This is really great Ben! I'm CC'ing Khushil on this bug as he has been thinking about this as well.

Comment 4

[Khushil Mistry [:khushil324]]

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.

Comment 5

[David R.]

So, I'm still a lurker, but just to add my two cents: I really like what Ben suggested. I've tried a couple times to figure out how to create an extension or make a real change to Thunderbird itself. Each time I end up stalled by not being able to find the docs, or by not being sure if the docs are applicable. 

I think I'll link to that topic I created last year: https://discourse.mozilla.org/t/consolidating-documentation-and-communication/27849/3 There's some documentation related comments. Specifically, I still think it's a good idea to consolidate all Thunderbird docs into one location.

As a start to the index Ben suggested, would a spreadsheet of links to Thunderbird docs be a good method? I'm thinking of something like a Google Sheet where we have a column for the link, then columns that classify it as "up to date", "deprecated", etc. With Google Sheets people can leave comments. I don't know if Google Sheets is the best way to do something like this, but something like it? Or, maybe, a GitHub repo?

Comment 6

[u520405]

Instead of Google Docs I'd prefer using https://ethercalc.org/ and instead of GitHub, please let's consider using GitLab.

It's important to avoid using any and all proprietary SaaS, software and tools when working on this. We need to avoid them when inviting others to contribute to a project. It's directly against Mozilla's mission to "Keep the internet open and accessible to all." and highly incoherent.

This list also has dozens of useful alternatives: https://degooglisons-internet.org/en/alternatives

Comment 7

[Ryan Lee Sipes]

There's been some movement on this:

The documentation repo is here: https://github.com/thundernest/developer-docs

You can view the documentation via this site: https://developer.thunderbird.net

I would like to get the documentation here to match with what Khushil and Ben outlined above.

Comment 8

[Ryan Lee Sipes]

Okay Khushil and Ben. I have added quite a bit of documentation to the website. But it could use some ideas and I still need to fill in the proper steps for Fixing a Bug. Let me know your thoughts or feel free to send me a pull request.

Comment 9

[Khushil Mistry [:khushil324]]

(In reply to Ryan Sipes from comment #8)

Okay Khushil and Ben. I have added quite a bit of documentation to the website. But it could use some ideas and I still need to fill in the proper steps for Fixing a Bug. Let me know your thoughts or feel free to send me a pull request.

Yeah Sure, I will document one of my starting contribution/bug-fixing and make a PR.

Comment 10

[Ryan Lee Sipes]

https://developer.thunderbird.net has come along quite well. Could still use some more information on how to hack on core components. But at least there has been significant progress.

Ben's "Getting Started" outline is pretty much reproduced in the code. But the more meaty parts of the API documentation and how to build anything beyond the most basic is missing.

Comment 11

[Ryan Lee Sipes]

Closing this as there are many improvements that can be made to the developer documentation. But it is healthy and growing.

Comment 12

[Ryan Lee Sipes]

Removing the needinfo.