[documentation] Add documentation about adding a new DevTools preference

RESOLVED FIXED in Firefox 57

Status

DevTools
General
RESOLVED FIXED
10 months ago
7 days ago

People

(Reporter: jdescottes, Unassigned)

Tracking

unspecified
Firefox 57

Firefox Tracking Flags

(firefox57 fixed)

Details

(Whiteboard: [dt-docs])

MozReview Requests

Submitter Diff Changes Open Issues Last Updated
Loading...
Error loading review requests:

Attachments

(1 attachment)

Adding a preference to DevTools cna be confusing, especially for contributors using launchpad. Each project using launchpad has its own way of defining default prefs.

We should have a documentation page that goes through:
- an overview of the prefs service we use in Firefox (Services.prefs)
- the shim from devtools-modules that mimics Services.prefs for launchpad projects
- how to add a new pref (with specific sections for each project using launchpad) 

I opened a related issue on GitHub : https://github.com/devtools-html/devtools-core/issues/612 

The goal would be to improve the error messages of our services shim to point to the documentation page created here.
(Reporter)

Updated

10 months ago
Whiteboard: [dt-docs]
Comment hidden (mozreview-request)

Comment 2

10 months ago
mozreview-review
Comment on attachment 8902202 [details]
Bug 1393767 - add documentation about DevTools preferences;

https://reviewboard.mozilla.org/r/173682/#review179112

::: devtools/docs/SUMMARY.md:9
(Diff revision 1)
>  * [Getting started](getting-started/README.md)
>    * [Where is the code?](getting-started/where-is-the-code.md)
>    * [Architecture overview](getting-started/architecture-overview.md)
>    * [Set up to build DevTools](getting-started/build.md)
>    * [Development profiles](getting-started/development-profiles.md)
> +  * [Preferences in DevTools](getting-started/preferences.md)

I don't think this should belong in the 'getting started' section - it would be totally overwhelming for a beginner! (which is the aim of the section).

In fact, I believe it should possibly have its own section.

Are there other cases in which we store data in the profiles? If not, I'd place this new file above the 'Automated tests' section on the summary.md file.

Otherwise if we're storing more data (and I think we are, with IndexedDB?), we should have a section about "Storing data" or similar, and have this as a child section. It's fine if it's only one page for now, we can add more content afterwards (file a bug!)

::: devtools/docs/getting-started/preferences.md:1
(Diff revision 1)
> +# Preferences in DevTools

This is the DevTools documentation, so I don't think we need to reiterate 'DevTools' so much that the title is 'in DevTools', etc.

I have lots of suggestions but I think it'll be easier/shorter to file a bug and send my patch :)
Attachment #8902202 - Flags: review?(spenades) → review-
Comment hidden (mozreview-request)
(Reporter)

Comment 4

10 months ago
mozreview-review-reply
Comment on attachment 8902202 [details]
Bug 1393767 - add documentation about DevTools preferences;

https://reviewboard.mozilla.org/r/173682/#review179112

> I don't think this should belong in the 'getting started' section - it would be totally overwhelming for a beginner! (which is the aim of the section).
> 
> In fact, I believe it should possibly have its own section.
> 
> Are there other cases in which we store data in the profiles? If not, I'd place this new file above the 'Automated tests' section on the summary.md file.
> 
> Otherwise if we're storing more data (and I think we are, with IndexedDB?), we should have a section about "Storing data" or similar, and have this as a child section. It's fine if it's only one page for now, we can add more content afterwards (file a bug!)

Erf sorry I missed the review! Thanks!

> In fact, I believe it should possibly have its own section.

Yes, I was not sure about the category either. While technically it's true that we use indexeddb for devtools, I am ot sure it is the same kind of documentation. Until we have doc for this I'd prefer to keep preferences as a single page then.

> This is the DevTools documentation, so I don't think we need to reiterate 'DevTools' so much that the title is 'in DevTools', etc.
> 
> I have lots of suggestions but I think it'll be easier/shorter to file a bug and send my patch :)

Fixed. Feel free to modify in a followup!

Comment 5

10 months ago
mozreview-review
Comment on attachment 8902202 [details]
Bug 1393767 - add documentation about DevTools preferences;

https://reviewboard.mozilla.org/r/173682/#review180470

this is so much better! I will follow up!
Attachment #8902202 - Flags: review?(spenades) → review+

Comment 6

10 months ago
Pushed by jdescottes@mozilla.com:
https://hg.mozilla.org/integration/autoland/rev/dd20802d1472
add documentation about DevTools preferences;r=sole

Comment 7

10 months ago
bugherder
https://hg.mozilla.org/mozilla-central/rev/dd20802d1472
Status: NEW → RESOLVED
Last Resolved: 10 months ago
status-firefox57: --- → fixed
Resolution: --- → FIXED
Target Milestone: --- → Firefox 57

Updated

7 days ago
Product: Firefox → DevTools
You need to log in before you can comment on or make changes to this bug.