Add legacy porting guide

rsjtdrjgfuzkfg commented 4 years ago

There does not yet seem to be a document that collects the information needed to get started on porting legacy add-ons to MailExtensions. Given that the information is spread over multiple repositories without obvious relationship, I feel that it would be a good idea to have a central guide on the one platform where the guide for 68 was located.

This PR introduces the first draft of a guide to port legacy add-ons to 78. It is certainly not exhaustive, but it covers some (most?) topics that might come up when planning a port.

(It is likely that I missed something, feel free to extend / rewrite as you like.)

jobisoft commented 4 years ago

Thanks for your work! I will have a look as soon as my kids daycare opens up again next week.

rsjtdrjgfuzkfg commented 4 years ago

@jobisoft does your silence mean that you still haven't reviewed the article, or that you have some reservations and need more time to come up with alternatives?

Given that TB 78 is already in beta I think some form of porting guide should be published soon.

(One topic I noticed missing since the last commit is accessing WebExtension things from browser contexts, but I don't think it is reasonable to keep updating this pull request without any feedback.)

jobisoft commented 4 years ago

It just missing time. I am starting to get more active here again. First I needed to get one of my own projects done (quicktext) and there are other things my mind is distracted by. But everyday I plan to look at this. Time goes by so fast and whoops the day is gone. I put this top priority for tomorrow, but I only have half a day. Next slot is on Monday. Thanks for your contribution!

jobisoft commented 4 years ago

I updated the first two sections. Could you go through it and give feedback? https://github.com/thundernest/developer-docs/pull/73/commits/5023ae3cc450c1a41e5037869f9cb4ea875fdb45

rsjtdrjgfuzkfg commented 4 years ago

@jobisoft sorry, I made the mistake of using GitHub instead of proper git which seems to be unable to merge things and blindly replaced your changes.

jobisoft commented 4 years ago

I made some more updates:

created experiments.md, which is at the moment just a text block storage
minor rewordings
removed file-url stuff from chrome.manifest section, will be covered in the experiment page
reworked the overlay section, still missing exampes
windows.create() -> for me relative urls never worked, only absolute from the addons root (did it work for you?)
added a line bewteen text and code blocks
geoff added storage to the list of supported WebExt API, but not yet the linkable header :-(

Todo is still:

examples in the overlay section
section about locales and our locale conversion script and how to access the new locales from within an experiement (there is a dedicated method part of the extension object, need to look it up)
maybe also cover, how to generally access WX API from within an experiement
reorder: move options and lcoales up

jobisoft commented 4 years ago

One thing that crossed my mind: Your newly created convert-legacy.md should be merged directly into the main add-ons/updating/tb78/README.md file. The experimental stuff written in readme is sort of redundancy of what we have in the new doc. So it can all be merged together. We do have now a dedicated page for experiments.

jobisoft commented 4 years ago

So that we not both run into merge conflicts again, I would suggest that only one of us edits the file directly, the other one uses the suggestion feature? How about I continue to edit convert-legacy.md and you may work (if you like of course) on the experimets.md?

The PR as it is will merge perfectly fine into master.

rsjtdrjgfuzkfg commented 4 years ago

Regarding parallel editing: if you want, you can edit all three files for now. I will stick to suggestions – I don't think that major changes by me are reasonable until we get this merged.

If you want to merge the experiment document without further changes, I'd only request to add a headline.

The only topic I think about adding right now would be WebExt/Experiment communication – but I don't think it would be in the new scope of the main article anyway so it is likely reasonable to do that in a separate PR on the experiments document.

jobisoft commented 4 years ago

If you want to merge the experiment document without further changes, I'd only request to add a headline.

Sure.

Are you ok with me merging all the new content of convert-legacy.md directly into the main Readme? You will still be mentioned as author as I do it as part of this PR and thus in your branch.

rsjtdrjgfuzkfg commented 4 years ago

Are you ok with me merging all the new content of convert-legacy.md directly into the main Readme?

Sure.

jobisoft commented 4 years ago

I merged it today and made a few more improvements (outside of this PR). What do you think? https://developer.thunderbird.net/add-ons/updating/tb78

As much of the work is from you, I would like to make you visible. Do you want that? How?

Do you mind switching into chat https://chat.mozilla.org/#/room/#tb-addon-developers:mozilla.org

to continue discussing the "Experiments Guide"?

Thanks for all your help.

thunderbird / developer-docs

Add legacy porting guide #73