mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-11-24 13:21:05 +00:00
Bug 1508583 - Improve sections under getting started. r=ladybenko,Ola
MozReview-Commit-ID: 9RRTngBSF2F Differential Revision: https://phabricator.services.mozilla.com/D13988 --HG-- rename : devtools/docs/README.md => devtools/docs/about-documentation.md rename : devtools/docs/contributing/code-reviews.md => devtools/docs/contributing/code-reviews-checklist.md extra : moz-landing-system : lando
This commit is contained in:
sole
parent
e3f392ffc0
commit
e76a9c3329
@ -1,33 +1,21 @@
|
||||
# Firefox Developer Tools
|
||||
|
||||
**NOTE:** This is the documentation *for working on* the Developer Tools. If you are looking for help with *using* the tools, please check out [the end user documentation](https://developer.mozilla.org/en-US/docs/Tools) instead.
|
||||
|
||||
---
|
||||
|
||||
**Hello!**
|
||||
|
||||
This documentation is for developers who want to work on the developer tools. [Get started here](./getting-started/).
|
||||
First of all, **thank you for making it this far!**
|
||||
|
||||
If you are looking for end user documentation, check out [this MDN page](https://developer.mozilla.org/en-US/docs/Tools) instead.
|
||||
Developer Tools is a complex web application, and learning the code base will take some time, even if you're a very experienced contributor to other projects.
|
||||
|
||||
Happy developing!
|
||||
Likewise, getting and building the code locally, sending contributions for review, and other essential tasks can take a bit longer and be a bit different from what you're used to seeing.
|
||||
|
||||
## About this documentation
|
||||
But there are good news: most of the initial, lengthy tasks don't need to be repeated once your computer is set up. And there's a huge infrastructure in place (both technical and people) to ensure that many commits can land into the Firefox repository with the peace of mind that the code is peer reviewed, can be built and passes the tests, in multiple configurations and operating systems.
|
||||
|
||||
This guide is built with MarkDown files and [GitBook](https://github.com/GitbookIO/gitbook).
|
||||
So don't be afraid of committing errors: you will. This is what happens to us all the time.
|
||||
|
||||
The source code for this documentation is distributed with the source code for the tools, in the `docs/` folder.
|
||||
It's a big system, and no one knows *absolutely everything*. What we do know is that we are not going to break Firefox. If we do something wrong, the system will let us know before we mess things up for real. Users won't ever notice, and you will learn a new thing.
|
||||
|
||||
If you want to contribute to the documentation, [clone the repository](./getting-started/build.md#getting-the-code), make your changes locally, and then regenerate the book to see how it looks like before submitting a patch:
|
||||
|
||||
```bash
|
||||
# Install GitBook locally
|
||||
npm install -g gitbook-cli
|
||||
|
||||
# Go into the docs directory
|
||||
cd /path/to/mozilla-central/devtools/docs/
|
||||
|
||||
# Generate the docs and start a local server
|
||||
gitbook serve
|
||||
|
||||
# You can now navigate to localhost:4000 to see the output
|
||||
|
||||
# Or build the book only (this places the output into `docs/_book`)
|
||||
gitbook build
|
||||
```
|
||||
[Let's get started](./getting-started/).
|
||||
|
||||
@ -2,17 +2,23 @@
|
||||
# Summary
|
||||
|
||||
* [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)
|
||||
* [Get a Bugzilla account](getting-started/bugzilla.md)
|
||||
* [Get and build the code](getting-started/build.md)
|
||||
* [Create a development profile](getting-started/development-profiles.md)
|
||||
* [Contributing](./contributing.md)
|
||||
* [Find bugs to work on](./contributing/find-bugs.md)
|
||||
* [How to fix a bug](./contributing/fixing-bugs.md)
|
||||
* [Code reviews](./contributing/code-reviews.md)
|
||||
* [Set up for code reviews](./contributing/code-reviews-setup.md)
|
||||
* [Find a reviewer](./contributing/code-reviews-find-reviewer.md)
|
||||
* [Send your code for review](./contributing/making-prs.md)
|
||||
* [Reviews checklist](./contributing/code-reviews-checklist.md)
|
||||
* [Landing code](./contributing/landing-code.md)
|
||||
* [Levelling up](./contributing/levelling-up.md)
|
||||
* [Coding standards](./contributing/coding-standards.md)
|
||||
* [JavaScript](./contributing/javascript.md)
|
||||
* [ESLint](./contributing/eslint.md)
|
||||
* [CSS](./contributing/css.md)
|
||||
* [Creating and sending patches](./contributing/making-prs.md)
|
||||
* [Code reviews](./contributing/code-reviews.md)
|
||||
* [Filing good bugs](./contributing/filing-good-bugs.md)
|
||||
* [Investigating performance issues](./contributing/performance.md)
|
||||
* [Writing efficient React code](./contributing/react-performance-tips.md)
|
||||
@ -25,7 +31,6 @@
|
||||
* [Debugging intermittent failures](tests/debugging-intermittents.md)
|
||||
* [Performance tests (DAMP)](tests/performance-tests.md)
|
||||
* [Writing a new test](tests/writing-perf-tests.md)
|
||||
* [Bugs and issue trackers](bugs-issues.md)
|
||||
* [Files and directories](files/README.md)
|
||||
* [Adding New Files](files/adding-files.md)
|
||||
* [Tool Architectures](tools/tools.md)
|
||||
@ -56,3 +61,4 @@
|
||||
* [Registering A New Actor](backend/actor-registration.md)
|
||||
* [Actor Best Practices](backend/actor-best-practices.md)
|
||||
* [Preferences](preferences.md)
|
||||
* [About this documentation](about-documentation.md)
|
||||
|
||||
24
devtools/docs/about-documentation.md
Normal file
24
devtools/docs/about-documentation.md
Normal file
@ -0,0 +1,24 @@
|
||||
# About this documentation
|
||||
|
||||
This guide is built with MarkDown files and [GitBook](https://github.com/GitbookIO/gitbook).
|
||||
|
||||
The source code for this documentation is distributed with the source code for the tools, in the `docs/` folder.
|
||||
|
||||
If you want to contribute to the documentation, [clone the repository](./getting-started/build.md#getting-the-code), make your changes locally, and then regenerate the book to see how it looks like before submitting a patch:
|
||||
|
||||
```bash
|
||||
# Install GitBook locally
|
||||
npm install -g gitbook-cli
|
||||
|
||||
# Go into the docs directory
|
||||
cd /path/to/mozilla-central/devtools/docs/
|
||||
|
||||
# Generate the docs and start a local server
|
||||
gitbook serve
|
||||
|
||||
# You can now navigate to localhost:4000 in your browser to see the output
|
||||
open http://localhost:4000 # this would work in MacOS
|
||||
|
||||
# Or build the book only (this places the output into `docs/_book`)
|
||||
gitbook build
|
||||
```
|
||||
@ -1,16 +1,47 @@
|
||||
# Contributing
|
||||
|
||||
<!--TODO: make this less code focused and take ideas from debugger.html's contributing.md file-->
|
||||
Thank you for taking the time to contribute! There are several areas where you can help: code, UX, bugs, talking about the DevTools, etc...
|
||||
|
||||
Thank you for taking the time to contribute!
|
||||
---
|
||||
|
||||
Many people become contributors to implement a feature they miss, or want to fix something that annoys them. If you want to help, but don't know where to start, you could [look at our list of things to do](./bugs-issues.md). Alternatively, you might want to [report an issue or request a feature](./filing-good-bugs.md).
|
||||
## 👉 Code of conduct 👈
|
||||
|
||||
If it's your first time contributing, you should also read the documentation on [coding standards](./contributing/coding-standards.md). This might help you with questions such as what style of code to use, how to name new files (if you have to add any), tools we use to run automated checks, etc.
|
||||
We strive for collaboration with [mutual respect](https://searchfox.org/mozilla-central/source/devtools/CODE_OF_CONDUCT.md) for each other. Mozilla also has a set of [participation guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/) which goes into greater detail specific to Mozilla employees and contributors.
|
||||
|
||||
Once you think your work is ready to be shared, [learn how to make and submit a patch](./contributing/making-prs.md).
|
||||
Please read the two links above before getting involved. **Contributions that don't abide by the code of conduct and participation guidelines will be rejected**.
|
||||
|
||||
A member of the team will look at your contribution, and [perform a code review](./contributing/code-reviews.md).
|
||||
---
|
||||
|
||||
* If all goes well, your patch will be merged into the project. Congratulations!
|
||||
* If there are changes to be made, the reviewer will let you know, and you can send the updated patch again.
|
||||
## Help with code
|
||||
|
||||
Whether you're an external contributor or a Mozilla employee, the process to get your code into the repository is essentially the same:
|
||||
|
||||
* You [find a bug to work on](./contributing/find-bugs.md) (*note: we use bugs to track 'broken' things, new features and even discussions*).
|
||||
* [Work on the bug](./contributing/fixing-bugs.md).
|
||||
* [Request a review](./contributing/making-prs.md) for your code.
|
||||
* Land the code in the repository.
|
||||
* And you've contributed—well done 😀
|
||||
|
||||
## Help with design and UX
|
||||
|
||||
If you're more interested in user experience (think: wireframes, workflows, navigations... and not necessarily implementation details), please have a look at the [UX](https://github.com/devtools-html/ux) repository—our friendly designers will be more than happy to welcome you onboard. You can also have a look at the [issues](https://github.com/devtools-html/ux/issues) they are considering right now, to get an idea of how it works.
|
||||
|
||||
## Help with BUGS! 🐛🐞 <!--TODO: we might want to split this out to another page with more detail, in addition to this introductory section-->
|
||||
|
||||
Not less importantly, we also love **when people file bugs**. They help us a lot and are very valuable (specially when they come with reproducible steps, e.g. in the case of crashes or malfunctions). Here is a short [guide on how to file good bugs](./filing-good-bugs.md) if you've never done it before (or if you need a reminder).
|
||||
|
||||
Another thing that is super valuable is **reproducing** bugs (to validate they're happening in more than one environment), and also **completing** bugs, i.e. ensuring the bug has steps to reproduce, a test case, etc, as [mentioned on the guide](./filing-good-bugs.md). This saves time for the person(s) who will work on the bug, as then they can jump straight to fixing or implementing whatever is needed, instead of doing research work. If you can do any of these for a given bug, add a comment with the additional data that you found out.
|
||||
|
||||
Likewise, if you think that a bug is solved, because you can't reproduce it and doesn't happen any more, this is also useful to know. We can always do with closing more bugs, so please leave a comment detailing as much information as you can provide 😀
|
||||
|
||||
## Talking about the tools <!--TODO: same as above, might want a separate page on talking and maybe collecting talks?-->
|
||||
|
||||
We really love when people talk about our work. Be it in a blog post, or in your favourite social media network, or user group, conference, you name it! We'd love to read/watch your article/talk, so please get in touch if you do.
|
||||
|
||||
Answering other people's questions in [our Discourse forum](https://discourse.mozilla.org/c/devtools) or [developer mailing list](https://groups.google.com/forum/#!forum/mozilla.dev.developer-tools) is also helpful.
|
||||
|
||||
## Other areas
|
||||
|
||||
The above is not a comprehensive list; if you think you can help some other way that is not here, feel free to do it!
|
||||
|
||||
**Whatever you choose to do, thank you so much for helping us** ❤️
|
||||
|
||||
59
devtools/docs/contributing/code-reviews-checklist.md
Normal file
59
devtools/docs/contributing/code-reviews-checklist.md
Normal file
@ -0,0 +1,59 @@
|
||||
# Code reviews checklist
|
||||
|
||||
This checklist is primarily aimed at reviewers, as it lists important points to check while reviewing a patch.
|
||||
|
||||
It can also be useful for patch authors: if the changes comply with these guidelines, then it's more likely the review will be approved.
|
||||
|
||||
## Bug status and patch file
|
||||
|
||||
* Bug status is assigned, and assignee is correctly set.
|
||||
* Commit title and message follow [the conventions](https://developer.mozilla.org/en-US/docs/Mercurial/Using_Mercurial#Commit_Message_Conventions).
|
||||
* Commit message says [what is being changed and why](http://mozilla-version-control-tools.readthedocs.org/en/latest/mozreview/commits.html#write-detailed-commit-messages).
|
||||
* Patch applies locally to current sources with no merge required.
|
||||
* Check that every new file introduced by the patch has the proper Mozilla license header: https://www.mozilla.org/en-US/MPL/headers/
|
||||
|
||||
## Manual testing
|
||||
|
||||
* Verify:
|
||||
* if it's a new feature, the patch implements it.
|
||||
* if it's a fix, the patch fixes the bug it addresses.
|
||||
* Report any problems you find in the global review comment.
|
||||
* Decide if any of those problems should block landing the change, or if they can be filed as follow-up bugs instead, to be fixed later.
|
||||
|
||||
## Automated testing
|
||||
|
||||
* Run new/modified tests, [with and without e10s](../tests/writing-tests.md#electrolysis).
|
||||
* Watch out for tests that pass but log exceptions or end before protocol requests are handled.
|
||||
* Watch out for slow/long tests: suggest many small tests rather than single long tests.
|
||||
* Watch out for new tests written as integration tests instead of as unit tests: unit tests should be the preferred option, when possible.
|
||||
|
||||
## Code review
|
||||
|
||||
* Code changes:
|
||||
* Review only what was changed by the contributor.
|
||||
* Code formatting follows [our ESLint rules](eslint.md) and [coding standards](./coding-standards.md).
|
||||
* Code is properly commented, JSDoc is updated, new "public" methods all have JSDoc, see the [comment guidelines](./javascript.md#comments).
|
||||
* If Promise code was added/modified, the right promise syntax is used and rejections are handled. See [asynchronous code](./javascript.md#asynchronous-code).
|
||||
* If a CSS file is added/modified, it follows [the CSS guidelines](./css.md).
|
||||
* If a React or Redux module is added/modified, it follows the [React/Redux guidelines](./javascript.md#react--redux).
|
||||
* If DevTools server code that should run in a worker is added/modified then it shouldn't use Services
|
||||
* Test changes:
|
||||
* The feature or bug is [tested by new tests, or a modification of existing tests](../tests/writing-tests.md).
|
||||
* [Test logging](../tests/writing-tests.md#logs-and-comments) is sufficient to help investigating test failures/timeouts.
|
||||
* [Test is e10s compliant](../tests/writing-tests.md#e10s-electrolysis) (no CPOWs, no content, etc…).
|
||||
* Tests are [clean and maintainable](../tests/writing-tests.md#writing-clean-maintainable-test-code).
|
||||
* A try push has started (or even better, is green already).
|
||||
* User facing changes:
|
||||
* If a new piece of UI or new user interaction is added/modified, then UX is `ui-review?` on the bug.<!--TODO this needs updating with the new process-->
|
||||
* If a user facing string has been added, it is localized and follows [the localization guidelines](../files/adding-files.md#localization-l10n).
|
||||
* If a user-facing string has changed meaning, [the key has been updated](https://developer.mozilla.org/en-US/docs/Mozilla/Localization/Localization_content_best_practices#Changing_existing_strings).
|
||||
* If a new image is added, it is a SVG image or there is a reason for not using a SVG.
|
||||
* If a SVG is added/modified, it follows [the SVG guidelines](../frontend/svgs.md).
|
||||
* If a documented feature has been modified, the keyword `dev-doc-needed` is present on the bug.
|
||||
|
||||
## Finalize the review
|
||||
|
||||
* R+: the code should land as soon as possible.
|
||||
* R+ with comments: there are some comments, but they are minor enough, or don't require a new review once addressed, trust the author.
|
||||
* R cancel / R- / F+: there is something wrong with the code, and a new review is required.
|
||||
|
||||
7
devtools/docs/contributing/code-reviews-find-reviewer.md
Normal file
7
devtools/docs/contributing/code-reviews-find-reviewer.md
Normal file
@ -0,0 +1,7 @@
|
||||
# Finding suitable reviewers
|
||||
|
||||
The code in DevTools is divided into modules (because there's just so much code it's impossible for one person to know *everything* off the top of their head).
|
||||
|
||||
Each module has one or more "owners", who know a lot about it. And they're the people you want to ask to review your code 😀
|
||||
|
||||
You might already know who is the reviewer (perhaps the person that is mentoring the bug, perhaps your team mate), but in case of doubt, you can [consult this list of people and modules](https://firefox-dev.tools/#people-and-modules).
|
||||
34
devtools/docs/contributing/code-reviews-setup.md
Normal file
34
devtools/docs/contributing/code-reviews-setup.md
Normal file
@ -0,0 +1,34 @@
|
||||
# Set up for code reviews
|
||||
|
||||
There are two things you need to do before you can get a code review, although you only need to do this once 😃
|
||||
|
||||
## Set up to get code reviews in Phabricator
|
||||
|
||||
We use an online tool called Phabricator for code reviews. To create an account in Phabricator, you first need the Bugzilla account that you created earlier. If you don't have one, [create it now](../getting-started/bugzilla.md).
|
||||
|
||||
---
|
||||
|
||||
⚠️ *IMPORTANT:* ⚠️️️
|
||||
|
||||
It's helpful to have the same user name in both Bugzilla and Phabricator, so that people always know how to find you.
|
||||
|
||||
Bugzilla's `Real name` field can be edited after the fact, but you cannot change Phabricator's username once the account has been created.
|
||||
|
||||
If you added an `:ircnickname` in your Bugzilla's `Real name`, Phabricator will use that to pre-fill the username field when you create the account. **Please double check you like the proposed username, and make any corrections before you register**.
|
||||
|
||||
---
|
||||
|
||||
Once you understand the above, please [create a Phabricator account](https://moz-conduit.readthedocs.io/en/latest/phabricator-user.html#creating-an-account).
|
||||
|
||||
|
||||
|
||||
## Set up to send code for review
|
||||
|
||||
There are two ways of doing this (sorry, let us explain!):
|
||||
|
||||
* you can use [Arcanist](https://moz-conduit.readthedocs.io/en/latest/arcanist-user.html), which is the official command line tool that accompanies Phabricator, and should be enough for most of the cases.
|
||||
* or you could use [moz-phab](https://moz-conduit.readthedocs.io/en/latest/phabricator-user.html#using-moz-phab), which is a Mozilla-developed wrapper for Arcanist that makes it work better with the "Mozilla workflow".
|
||||
|
||||
**We recommend you use Arcanist** for now, unless you are more experienced and know what you're doing, or want to take advantage of `moz-phab`'s features. You need to install Arcanist for `moz-phab` to work anyway.
|
||||
|
||||
If you decide to use `moz-phab`, please be aware that we started using this new tool quite recently, and you might find bugs (or things that don't feel quite right), in which case you could either [have a look at the existing bugs](https://bugzilla.mozilla.org/buglist.cgi?product=Conduit&component=Review%20Wrapper&resolution=---) to see if someone else has encountered this again, or simply [file a bug](https://bugzilla.mozilla.org/enter_bug.cgi?product=Conduit&component=Review%20Wrapper) using your fancy new Bugzilla account 😀
|
||||
@ -1,59 +1,7 @@
|
||||
# Code reviews
|
||||
|
||||
This checklist is primarily aimed at reviewers, as it lists important points to check while reviewing a patch.
|
||||
A review is required before code is added to Mozilla's repository. In addition, contrary to what you might have seen in other open source projects, code is not pushed directly to the repository. Instead, once the code is approved by reviewers, they will *request* the code to be *landed* on the repository.
|
||||
|
||||
It can also be useful for patch authors: if the changes comply with these guidelines, then it's more likely the review will be approved.
|
||||
|
||||
## Bug status and patch file
|
||||
<!--TODO: update when we move to github-->
|
||||
* Bug status is assigned, and assignee is correctly set.
|
||||
* Commit title and message follow [the conventions](https://developer.mozilla.org/en-US/docs/Mercurial/Using_Mercurial#Commit_Message_Conventions).
|
||||
* Commit message says [what is being changed and why](http://mozilla-version-control-tools.readthedocs.org/en/latest/mozreview/commits.html#write-detailed-commit-messages).
|
||||
* Patch applies locally to current sources with no merge required.
|
||||
* Check that every new file introduced by the patch has the proper Mozilla license header: https://www.mozilla.org/en-US/MPL/headers/
|
||||
|
||||
## Manual testing
|
||||
|
||||
* Verify:
|
||||
* if it's a new feature, the patch implements it.
|
||||
* if it's a fix, the patch fixes the bug it addresses.
|
||||
* Report any problems you find in the global review comment.
|
||||
* Decide if any of those problems should block landing the change, or if they can be filed as follow-up bugs instead, to be fixed later.
|
||||
|
||||
## Automated testing
|
||||
|
||||
* Run new/modified tests, [with and without e10s](../tests/writing-tests.md#electrolysis).
|
||||
* Watch out for tests that pass but log exceptions or end before protocol requests are handled.
|
||||
* Watch out for slow/long tests: suggest many small tests rather than single long tests.
|
||||
* Watch out for new tests written as integration tests instead of as unit tests: unit tests should be the preferred option, when possible.
|
||||
|
||||
## Code review
|
||||
|
||||
* Code changes:
|
||||
* Review only what was changed by the contributor.
|
||||
* Code formatting follows [our ESLint rules](eslint.md) and [coding standards](./coding-standards.md).
|
||||
* Code is properly commented, JSDoc is updated, new "public" methods all have JSDoc, see the [comment guidelines](./javascript.md#comments).
|
||||
* If Promise code was added/modified, the right promise syntax is used and rejections are handled. See [asynchronous code](./javascript.md#asynchronous-code).
|
||||
* If a CSS file is added/modified, it follows [the CSS guidelines](./css.md).
|
||||
* If a React or Redux module is added/modified, it follows the [React/Redux guidelines](./javascript.md#react--redux).
|
||||
* If DevTools server code that should run in a worker is added/modified then it shouldn't use Services
|
||||
* Test changes:
|
||||
* The feature or bug is [tested by new tests, or a modification of existing tests](../tests/writing-tests.md).
|
||||
* [Test logging](../tests/writing-tests.md#logs-and-comments) is sufficient to help investigating test failures/timeouts.
|
||||
* [Test is e10s compliant](../tests/writing-tests.md#e10s-electrolysis) (no CPOWs, no content, etc…).
|
||||
* Tests are [clean and maintainable](../tests/writing-tests.md#writing-clean-maintainable-test-code).
|
||||
* A try push has started (or even better, is green already)<!--TODO review and update with mentions to Travis, Circle or whatever it is we use when we move to GitHub-->.
|
||||
* User facing changes:
|
||||
* If a new piece of UI or new user interaction is added/modified, then UX is `ui-review?` on the bug.<!--TODO this needs updating with the new process-->
|
||||
* If a user facing string has been added, it is localized and follows [the localization guidelines](../files/adding-files.md#localization-l10n).
|
||||
* If a user-facing string has changed meaning, [the key has been updated](https://developer.mozilla.org/en-US/docs/Mozilla/Localization/Localization_content_best_practices#Changing_existing_strings).
|
||||
* If a new image is added, it is a SVG image or there is a reason for not using a SVG.
|
||||
* If a SVG is added/modified, it follows [the SVG guidelines](../frontend/svgs.md).
|
||||
* If a documented feature has been modified, the keyword `dev-doc-needed` is present on the bug.
|
||||
|
||||
## Finalize the review
|
||||
<!--TODO update with the GitHub workflow when we're there-->
|
||||
* R+: the code should land as soon as possible.
|
||||
* R+ with comments: there are some comments, but they are minor enough, or don't require a new review once addressed, trust the author.
|
||||
* R cancel / R- / F+: there is something wrong with the code, and a new review is required.
|
||||
All this can be done somehow manually, but we have infrastructure in place to help us with reviews and landing code.
|
||||
|
||||
The following sections will guide you towards getting your code reviewed and landed in the repository. Start by [setting up](./code-reviews-setup.md).
|
||||
|
||||
6
devtools/docs/contributing/find-bugs.md
Normal file
6
devtools/docs/contributing/find-bugs.md
Normal file
@ -0,0 +1,6 @@
|
||||
# Find bugs to work on
|
||||
|
||||
* Choose something from [the list of existing bugs](https://bugs.firefox-dev.tools/?easy&tool=all). You can filter by tools (e.g. only `Console` bugs), and also by good bugs for beginners.
|
||||
* Or if you would like to work on something that is not listed there, [file a bug in Bugzilla](https://bugzilla.mozilla.org/enter_bug.cgi?product=DevTools) (you'll need the Bugzilla account [you created earlier](../getting-started/bugzilla.md)) and ask for it to be assigned to you. Please also try to initiate a conversation in the bug first, to ensure that you don't work on something that will not be accepted (for example, if you think you found a bug, but the feature worked that way by design).
|
||||
|
||||
<!-- TODO: mention finding potential work that is captured as a TODO or FIXME comments, but doesn't have an associated filed bug -->
|
||||
168
devtools/docs/contributing/fixing-bugs.md
Normal file
168
devtools/docs/contributing/fixing-bugs.md
Normal file
@ -0,0 +1,168 @@
|
||||
# How to fix a bug
|
||||
|
||||
## Make sure you understand what needs to be done
|
||||
|
||||
If you're not quite sure of this, please add a comment requesting more information in the bug itself. It is absolutely fine to also talk to someone via other means (e.g. irc, email, in the office kitchen...), but it is good to come back to the bug and add the extra information, just in case you stop working on the bug at some point and someone else has to pick work where you left it.
|
||||
|
||||
## Find out where are the files that need changing
|
||||
|
||||
In an ideal world, the bug has this information from the start, but very often it doesn't.
|
||||
|
||||
If you're not yet familiar with the codebase, the [files and directories overview](../files/README.md) might help you find where things are.
|
||||
|
||||
If you know what you're looking for (e.g. a string that has a typo and needs correcting, or a function name that needs modifying), you can use a source code search engine:
|
||||
|
||||
* [Searchfox](http://searchfox.org/mozilla-central/source) (updated most frequently)
|
||||
* [DXR](http://dxr.mozilla.org/mozilla-central/source/) (less often)
|
||||
|
||||
It is a good idea to [add smart keyword searches](https://support.mozilla.org/en-US/kb/how-search-from-address-bar) for Searchfox or DXR to search faster.
|
||||
|
||||
You can also use your operating system's command line. For example, let's search for occurrences of `TODO` in the code base.
|
||||
|
||||
Within your command line prompt, `cd` to the `devtools` directory:
|
||||
|
||||
```bash
|
||||
cd ~/mozilla-central/devtools # use your actual folder name!
|
||||
grep -r 'TODO' .
|
||||
```
|
||||
|
||||
This will list all the places in the DevTools code that contain the `TODO` string. If there are too many instances, you can combine the above with `less`, to scroll and paginate the output of `grep`:
|
||||
|
||||
```bash
|
||||
grep -r 'TODO' . | less
|
||||
```
|
||||
|
||||
Press `q` to exit.
|
||||
|
||||
If after all of this you still can't find your bearings, add a comment in the bug asking for more information.
|
||||
|
||||
## How do you know that you have found what you were looking for?
|
||||
|
||||
There are a few options to confirm that you found the right files:
|
||||
|
||||
### If this is about changing a string...
|
||||
|
||||
Edit the file(s), and change the string (e.g. fix a typo). Rebuild, and run again:
|
||||
|
||||
```bash
|
||||
./mach build
|
||||
./mach run
|
||||
```
|
||||
Then go to the panel that displays the string you wanted to change.
|
||||
|
||||
Does the typo still occur? Or is the string being displayed the correct one now?
|
||||
|
||||
### If this is about changing JavaScript code...
|
||||
|
||||
If you think you found the right file to edit, add some logging statement on a place of the code which is likely to be executed (for example, on a class constructor):
|
||||
|
||||
```javascript
|
||||
// For front-end code
|
||||
console.log('hello friends\n');
|
||||
```
|
||||
|
||||
Or...
|
||||
|
||||
```javascript
|
||||
// For server code
|
||||
dump('hello friends\n');
|
||||
```
|
||||
|
||||
TIP: Whether to use one or another depends on the type of bug you're working on, but if you've just started in DevTools, it's highly likely you'll take a front-end bug first.
|
||||
|
||||
Then rebuild and run again:
|
||||
|
||||
```bash
|
||||
./mach build
|
||||
./mach run
|
||||
```
|
||||
|
||||
Go to the panel or initiate the action that is likely to result on the code being executed, and pay close attention to the output in your console.
|
||||
|
||||
Can you see `hello friends`? Then you found the file that you were looking for.
|
||||
|
||||
It's possible that you'll get a lot of other messages you don't care about now, but we can use `grep` to filter:
|
||||
|
||||
```bash
|
||||
./mach run | grep hello friends
|
||||
```
|
||||
|
||||
This will only show lines that contain `hello friends`. If you get an empty output after trying to get the code to execute, maybe this isn't the right file, or maybe you didn't trigger the action.
|
||||
|
||||
And that means it's time to ask for more information in the bug or from your colleagues. Tell them what you tried, so they don't have to figure that out themselves (saves everyone some time!).
|
||||
|
||||
### If this is about changing CSS code...
|
||||
|
||||
If you think you have found the right file and the right CSS selector, you could try to edit the file to insert some outrageously colourful rule (for example, a really thick bright blue border), then restart DevTools to see if the changes show up.
|
||||
|
||||
```css
|
||||
border: 4px solid blue;
|
||||
```
|
||||
|
||||
## NEXT: do whatever needs doing
|
||||
|
||||
This will always depend on the specific bug you're working on, so it's hard to provide guidance here.
|
||||
|
||||
The key aspect here is that if you have questions, you should not hesitate to ask. Ask your mentor, your manager, or [get in touch](https://firefox-dev.tools/#getting-in-touch). **You should just not get stuck**.
|
||||
|
||||
Some people find it difficult to recognise or even admit they're in such a situation, so some ways to describe 'stuck' could be:
|
||||
|
||||
* you've tried everything you could think of, nothing works, and do not know what else to do.
|
||||
* you have various ideas for things that can be done, and do not know which one to go for.
|
||||
* you have not learned anything new about the problem in the last one or two days.
|
||||
* you're starting to think about abandoning this bug and doing something else instead.
|
||||
* you don't know what to do, but are afraid of asking for help.
|
||||
|
||||
If you think *any* of the above describes you, ask for help!
|
||||
|
||||
Another tip you can use if you're afraid that you're wasting people's time is to timebox. For example, give yourself 2 hours to investigate. If you can't figure anything after that time has elapsed, stop and ask for help. It might be that you needed a key piece of information that was missing in the bug description, or you misunderstood something, or maybe even that you found a bug and that's why things didn't work even if they should! This is why it's important to call for help sooner rather than later.
|
||||
|
||||
### Useful references
|
||||
|
||||
#### Coding standards
|
||||
|
||||
If it's your first time contributing, the documentation on [coding standards](./coding-standards.md) might have answers to questions such as what style of code to use, how to name new files (if you have to add any), tools we use to run automated checks, etc.
|
||||
|
||||
#### Specialised guides
|
||||
|
||||
We also have a few guides explaining how to work on specific types of problems, for example: [investigating performance issues](./performance.md), or [writing efficient React code](./react-performance-tips.md). Please have a look at the sidebar or use the search box on top of the sidebar to see if there's something written about the type of bug you're working on.
|
||||
|
||||
If not, maybe you'll be able to contribute with one by the time you fix your bug!
|
||||
|
||||
#### MDN
|
||||
|
||||
[MDN Web Docs](http://developer.mozilla.org/) (also known as *MDN*) has a lot of information about HTML, CSS, JS, DOM, Web APIs, Gecko-specific APIs, and more.
|
||||
|
||||
## Run tests
|
||||
|
||||
We have several types of automated tests to help us when developing.
|
||||
|
||||
Some, like the linting tests, address coding style; others address functionality, such as unit and integration tests. This page has more [details on types of tests and how to run them](../tests.md).
|
||||
|
||||
You might want to run the unit and integration types of tests quite frequently, to confirm you're not breaking anything else. Depending on what you're doing, it might be even possible to run just one test file which addresses the specific change you're implementing:
|
||||
|
||||
```bash
|
||||
./mach test devtools/path/to/test.js
|
||||
```
|
||||
|
||||
Sometimes you might want to run a number of tests which are related to the bug you're fixing:
|
||||
|
||||
```bash
|
||||
./mach test devtools/path/to/test-thing-*.js
|
||||
```
|
||||
|
||||
At the beginning, it is entirely possible that you have no idea of where the tests are for the thing you're working on. Please ask for help! You will eventually learn your way around.
|
||||
|
||||
It is good etiquette to ensure the tests pass locally before asking for a code review. This includes linting tests. To run them, please [configure your system to run ESlint](./eslint.md), and then you can execute:
|
||||
|
||||
```bash
|
||||
./mach eslint devtools/path/to/files/you/changed
|
||||
```
|
||||
|
||||
Our tool for code review will run the linter automatically as well, but if you run this locally you'll get instant feedback, and avoid having to send an updated commit again.
|
||||
|
||||
## Time for a review
|
||||
|
||||
When you think you have fixed the bug, first let's celebrate a bit! Yay! Well done 😀
|
||||
|
||||
And now it's time to [get your code reviewed](./code-reviews.md).
|
||||
22
devtools/docs/contributing/landing-code.md
Normal file
22
devtools/docs/contributing/landing-code.md
Normal file
@ -0,0 +1,22 @@
|
||||
# Landing code (i.e. getting code into Mozilla's repository)
|
||||
|
||||
Code changes (patches) in Mozilla are not 'merged' in a sequential way, as it's the fashion in other popular projects. Here, the patches will be *applied* on top of the latest code, and will stay there if
|
||||
|
||||
1. the patch applies cleanly, without conflicts
|
||||
2. the patch doesn't cause 'bustage' (i.e. breaks the build)
|
||||
|
||||
Therefore, it's good to try and do smaller changes rather than bigger, specially if you're modifying files that many other people are working on simultaneously, to avoid conflicts and your patch being rejected. Otherwise you might need to rebase from the latest changes, try to write your changes on top of it, and submit this new diff.
|
||||
|
||||
Leaving potential conflicts aside, a patch can make its way into the repository in two ways:
|
||||
|
||||
## From Phabricator
|
||||
|
||||
Once a review has been approved, someone with enough privileges can request the code be merged, using the [Lando](https://moz-conduit.readthedocs.io/en/latest/lando-user.html) interface. These 'privileges' are "commit level access 3". You get these once you have successfully contributed with a number of patches. See [levelling up](./levelling-up.md) for more details.
|
||||
|
||||
If you don't have the privileges, you can also ask your mentor to land the code. In fact, they might even initiate that for you once the code review is approved.
|
||||
|
||||
## From Bugzilla
|
||||
|
||||
Another route is to request the landing using Bugzilla. Go to the bug, and add `checkin-needed` to the `Keywords` field.
|
||||
|
||||
Someone looks at bugs marked with `checkin-needed` a few times a day, verifies they have an associated **approved** review, and then attempts to land them.
|
||||
23
devtools/docs/contributing/levelling-up.md
Normal file
23
devtools/docs/contributing/levelling-up.md
Normal file
@ -0,0 +1,23 @@
|
||||
# Levelling up
|
||||
|
||||
Once you've fixed a few bugs, it's quite likely that we'll ask you to complete one or more of the following steps. They will grant you access to useful Mozilla infrastructure for testing or landing code automatically, so you can be more autonomous and able to contribute with less supervision.
|
||||
|
||||
If you're curious, the [Mozilla Commit Access Policy](https://www.mozilla.org/en-US/about/governance/policies/commit/access-policy/) page explains what does each level mean.
|
||||
|
||||
## Request commit access level 1
|
||||
|
||||
Once this is granted, you can use [the `Try` server](https://wiki.mozilla.org/ReleaseEngineering/TryServer) for running automated tests of your code.
|
||||
|
||||
To request this, [follow the instructions here](https://www.mozilla.org/en-US/about/governance/policies/commit/) to file a bug with the title "Commit Access (Level 1) for ${your name}", and continue with steps such as adding the public SSH key, etc (it's not enough with just filing the bug!).
|
||||
|
||||
The person that asked you to request this can also vouch for you.
|
||||
|
||||
## Request commit access level 3
|
||||
|
||||
Once this is granted, you will get access to Lando, the autoland feature.
|
||||
|
||||
To request this, [follow the instructions here](https://www.mozilla.org/en-US/about/governance/policies/commit/) to file a bug with the title "Commit Access (Level 3) for ${your name}".
|
||||
|
||||
The person that asked you to request this can also vouch for you, and at this point you might already know a few other people who will vouch for you. You need two vouchers.
|
||||
|
||||
If you reach this level, well done! That's amazing, and we're glad to have you on board 😄
|
||||
@ -1,6 +1,61 @@
|
||||
# Creating and sending patches <!--TODO: (in the future: Making Pull Requests)-->
|
||||
# Sending your code for review (also known as "sending patches")
|
||||
|
||||
## Creating a patch
|
||||
There are two ways of doing this. We'll first explain the recommended version, and then the alternative, which is older, and we don't recommend, but might be handy in some circumstances.
|
||||
|
||||
## Using Phabricator + Differential (RECOMMENDED)
|
||||
|
||||
First, commit your changes. For example:
|
||||
|
||||
```bash
|
||||
hg add /path/to/file/changed
|
||||
hg commit -m "Bug 1234567 - Implement feature XYZ."
|
||||
```
|
||||
|
||||
Then create a revision in Differential, using Arcanist (or `moz-phab`):
|
||||
|
||||
```bash
|
||||
arc diff
|
||||
```
|
||||
|
||||
You'll be taken to an editor to add extra details, although some of them might be prepopulated using the data in the commit message. Make sure the bug number is filled with the right value. You'll also be able to set reviewers here: enter the names you found using the instructions in the [previous step](./code-reviews-find-reviewer.md).
|
||||
|
||||
Save the changes and quit the editor. A revision will be created including those data and also the difference in code between your changes and the point in the repository where you based your work (this difference is sometimes called "a patch", as it's what you'd need to apply on the repository to get to the final state).
|
||||
|
||||
If you click on the provided URL for the revision, it'll bring you to Phabricator's interface, which the reviewer will visit as well in order to review the code. They will look at your changes and decide if they need any additional work, based on whether the changes do fix what the bug describes or not. To get a better idea of the types of things they will look at and verify, read the [code reviews checklist](./code-reviews-checklist.md).
|
||||
|
||||
The reviewer might suggest you do additional changes. For example, they might recommend using a helper that already exists (but you were not aware of), or they might recommend renaming things to make things clearer. Or they might recommend you do *less* things (e.g. if you changed other things that are out of scope for the bug). Or they might simply ask questions if things aren't clear. You can also ask questions if the comments are unclear or if you're unsure about parts of the code you're interacting with. Something that looks very obvious to one person might confuse others.
|
||||
|
||||
Hence, you might need to go back to the code and do some edits to address the issues and recommendations. Once you have done this, we want to amend the existing commit:
|
||||
|
||||
```bash
|
||||
hg commit --amend -m 'Address revision issues: rewrite to use helper helpfulHelper()'
|
||||
```
|
||||
|
||||
And submit the change again:
|
||||
|
||||
```bash
|
||||
arc diff
|
||||
```
|
||||
|
||||
This time, the editor that opens should have filled most of the information already. Add any missing information, save and quit the editor.
|
||||
|
||||
You might have to go through this cycle of uploading a diff and getting it reviewed several times, depending on the complexity of the bug.
|
||||
|
||||
**NOTE**: by default, Arcanist opens nano, which can be a bit confusing if you're not a nano user. You can override this by setting the `EDITOR` env variable. For instance, you could add this to your `.bash_profile` to set Vim as your preferred editor:
|
||||
|
||||
```bash
|
||||
export EDITOR="/usr/local/bin/vim"
|
||||
```
|
||||
|
||||
Once your code fixes the bug, and there are no more blocking issues, the reviewer will approve the review, and the code can be landed in the repository now.
|
||||
|
||||
For more information on using Arcanist, please refer to [their user guide](https://moz-conduit.readthedocs.io/en/latest/arcanist-user.html#submitting-and-updating-patches).
|
||||
|
||||
## Using Mercurial (not recommended)
|
||||
|
||||
We don't recommend to use this method as it's more manual and makes reviewing and landing code a bit more tedious.
|
||||
|
||||
### Creating a patch
|
||||
|
||||
To create a patch you need to first commit your changes and then export them to a patch file.
|
||||
|
||||
@ -9,19 +64,19 @@ hg commit -m 'your commit message'
|
||||
hg export > /path/to/your/patch
|
||||
```
|
||||
|
||||
## Commit messages
|
||||
### Commit messages
|
||||
|
||||
Commit messages should follow the pattern `Bug 1234567 - change description. r=reviewer`.
|
||||
|
||||
First is the bug number related to the patch. Then the description should explain what the patch changes. The last part is used to keep track of the reviewer for the patch.
|
||||
|
||||
## Submitting a patch
|
||||
### Submitting a patch
|
||||
|
||||
Once you have a patch file, add it as an attachment to the Bugzilla ticket you are working on and add the `feedback?` or `review?` flag depending on if you just want feedback and confirmation you're doing the right thing or if you think the patch is ready to land respectively. Read more about [how to submit a patch and the Bugzilla review cycle here](https://developer.mozilla.org/en-US/docs/Developer_Guide/How_to_Submit_a_Patch).
|
||||
|
||||
You can also take a look at the [Code Review Checklist](./code-reviews.md) as it contains a list of checks that your reviewer is likely to go over when reviewing your code.
|
||||
You can also take a look at the [Code Review Checklist](./code-reviews-checklist.md) as it contains a list of checks that your reviewer is likely to go over when reviewing your code.
|
||||
|
||||
## Squashing commits
|
||||
### Squashing commits
|
||||
|
||||
Sometimes you may be asked to squash your commits. Squashing means merging multiple commits into one in case you created multiple commits while working on a bug. Squashing bugs is easy!
|
||||
|
||||
|
||||
@ -1,12 +1,5 @@
|
||||
# Getting started
|
||||
|
||||
1. Learn [where the code is](./where-is-the-code.md) and about the [architecture](./architecture-overview.md) of the tools.
|
||||
2. [Set up your machine](./build.md) to build the tools, then [configure a development profile](development-profiles.md).
|
||||
3. You can now experiment by changing things and rebuilding, look at the [files and directories overview](../files/README.md) or you could also [find something to work on](../bugs-issues.md).
|
||||
This section describes [how to create a Bugzilla account](bugzilla.md), [how to build Firefox code locally](build.md), and how to [set up a development profile](development-profile.md), all of which are needed in order to contribute **code** to DevTools.
|
||||
|
||||
## Additional documentation
|
||||
|
||||
* [MDN Web Docs](http://developer.mozilla.org/) (also known as *MDN*) has a lot of information about XUL elements, HTML, JS, DOM, Web APIs, Gecko-specific APIs, and more.
|
||||
* [DXR](http://dxr.mozilla.org/mozilla-central/source/) is a source code search engine - search for symbols you want to learn about, eg. `Document`. [Searchfox](http://searchfox.org/mozilla-central/source) is an alternative.
|
||||
|
||||
It is a good idea to [add smart keyword searches](https://support.mozilla.org/en-US/kb/how-search-from-address-bar) for DXR and MDN, so you can search faster.
|
||||
If you want to help, but not necessarily writing code (UX, bugs...), the [contributing](../contributing.html) page can give you helpful pointers.
|
||||
|
||||
9
devtools/docs/getting-started/bugzilla.md
Normal file
9
devtools/docs/getting-started/bugzilla.md
Normal file
@ -0,0 +1,9 @@
|
||||
# Get a Bugzilla account
|
||||
|
||||
Mozilla's bug tracker is at [https://bugzilla.mozilla.org/](https://bugzilla.mozilla.org/), which is often abbreviated as `BMO`.
|
||||
|
||||
You don't need an account if you simply want to build the code and modify it, but you will need an account in Bugzilla if you want to file or comment on bugs, send patches, get assigned to bugs (so you can 'claim' them), etc.
|
||||
|
||||
**Note**: if you are a Mozilla employee, don’t use an email alias to sign up, use your full LDAP account.
|
||||
|
||||
To make yourself easier to find by other colleagues (for example when they're trying to set a reviewer for a patch), you can [edit the *real name* field](https://bugzilla.mozilla.org/userprefs.cgi?tab=account) to add your alias or any other word they might use to search for you there. The convention is to use something like `Your Name :alias :ldap/:ircnick`. For example: `Mary Smith :mary :msmith`
|
||||
@ -1,44 +1,85 @@
|
||||
# Set up to build Firefox Developer Tools
|
||||
|
||||
Since the tools are part of Firefox, we need to get and build Firefox's source code.
|
||||
|
||||
These are the steps we're going to look at:
|
||||
|
||||
* [Installing Mercurial](#installing-mercurial)
|
||||
* [Getting the code](#getting-the-code)
|
||||
* [Building and running locally](#building-and-running-locally)
|
||||
* [Rebuilding](#rebuilding)
|
||||
* [Artifact builds](#building-even-faster-with-artifact-builds) for even faster builds
|
||||
* [Maybe you don't even need to build](#maybe-you-dont-even-need-to-build)
|
||||
|
||||
## Getting the code
|
||||
## Installing Mercurial
|
||||
|
||||
The code is officially hosted on [a Mercurial repository](https://hg.mozilla.org/mozilla-central/). It takes a long time to clone, because the repository is **B I G**. So be prepared to be patient.
|
||||
Firefox's source code is hosted on [a Mercurial repository](https://hg.mozilla.org/mozilla-central/).
|
||||
|
||||
Please [install Mercurial](https://www.mercurial-scm.org/) if it's not already installed in your system. Its website provides [files for downloading](https://www.mercurial-scm.org/downloads) and also instructions for the most popular package managers. For example, if using Homebrew in macOS:
|
||||
|
||||
```bash
|
||||
brew install mercurial
|
||||
```
|
||||
|
||||
Or in Debian/Ubuntu Linux with apt-get:
|
||||
|
||||
```bash
|
||||
apt-get install mercurial
|
||||
```
|
||||
|
||||
## Getting the code
|
||||
|
||||
This will take a long time, because the repository is **B I G** (Firefox is more than 10 years old and there are lots of commits every day!). So please be patient.
|
||||
|
||||
You will also need a lot of disk space (about ~40Gb free).
|
||||
|
||||
```bash
|
||||
cd ~ # or the folder where you store your projects, for example ~/projects
|
||||
hg clone http://hg.mozilla.org/mozilla-central
|
||||
```
|
||||
|
||||
## Building and running locally
|
||||
|
||||
Fortunately, the Firefox team has made a very good job of automating the building process with bootstrap scripts and putting [documentation](https://developer.mozilla.org/docs/Mozilla/Developer_guide/Build_Instructions/Simple_Firefox_build) together.
|
||||
Although DevTools is written in JavaScript, the core of Firefox is not—we need tools such as compilers to build the C/C++/Rust code and turn it into binaries that our computer can run.
|
||||
|
||||
The very first time you are building Firefox, run:
|
||||
If you're a web developer, you might not be familiar with these tools, but fortunately, the Firefox team has made a very good job of automating the process of installing them with bootstrap scripts, and putting [documentation](https://developer.mozilla.org/docs/Mozilla/Developer_guide/Build_Instructions/Simple_Firefox_build) together. You don't *need* to read it now; as we'll provide a simplified way to build the code, but if you have any issues, please refer to the documentation.
|
||||
|
||||
Try building Firefox and downloading dependencies by running the following commands:
|
||||
|
||||
```bash
|
||||
./mach bootstrap
|
||||
```
|
||||
|
||||
This script might ask you questions, so it's recommended to keep an eye on the terminal while it's running—otherwise it will never finish!
|
||||
|
||||
After it finishes, you might be asked to add some lines to a `mozconfig` file. Create this file in the repository folder (i.e. in `~/mozilla-central`), then add the lines.
|
||||
|
||||
Then run this:
|
||||
|
||||
```bash
|
||||
./mach configure
|
||||
./mach build
|
||||
```
|
||||
|
||||
After that first successful build, you can just run:
|
||||
**Note:** if using Windows, you might need to type the commands without the `./`:
|
||||
|
||||
```bash
|
||||
mach bootstrap
|
||||
mach configure
|
||||
mach build
|
||||
```
|
||||
|
||||
If your system needs additional dependencies installed (for example, Python, or a compiler, etc) the above commands might fail, and various diagnostic messages will be printed to your screen. Follow their advice and then try running the command that failed again, until the three of them complete successfully.
|
||||
|
||||
Some error messages can be quite cryptic. It is a good idea to consult the [documentation](https://developer.mozilla.org/docs/Mozilla/Developer_guide/Build_Instructions/Simple_Firefox_build) specific to the platform you're using. Sometimes searching in the internet for the specific error message you get can help, and you can also [get in touch](https://firefox-dev.tools/#getting-in-touch) if you get stuck.
|
||||
|
||||
Once you complete a first successful build, you should be able to build again by running only this command:
|
||||
|
||||
```bash
|
||||
./mach build
|
||||
```
|
||||
|
||||
If your system needs additional dependencies installed (for example, Python, or a compiler, etc), various diagnostic messages will be printed to your screen. Follow their advice and try building again.
|
||||
|
||||
Building also takes a long time (specially on slow computers).
|
||||
|
||||
**Note:** if using Windows, you might need to type `mach build` instead (without the `./`).
|
||||
By the way, building takes a long time (specially on slow computers).
|
||||
|
||||
### Running your own compiled version of Firefox
|
||||
|
||||
@ -48,11 +89,15 @@ To run the Firefox you just compiled:
|
||||
./mach run
|
||||
```
|
||||
|
||||
This will run using an empty temporary profile which is discarded when you close the browser. We will look more into [persistent development profiles later](./development-profiles.md).
|
||||
This will run using an empty temporary profile which is discarded when you close the browser. We will look into [persistent development profiles later](./development-profiles.md). But first...
|
||||
|
||||
⭐️ **Time for some congratulations!** You managed to get Firefox's code, build tools and dependencies, and just run your very own copy of Firefox! Well done! ⭐ ️
|
||||
|
||||
### Rebuilding
|
||||
|
||||
Suppose you pulled the latest changes from the remote repository (or made your own changes) and want to build again.
|
||||
<!--TODO: it would be valuable to explain how to pull changes! -->
|
||||
|
||||
Suppose you pulled the latest changes from the remote repository (or made some changes, to experiment and see what happens) and want to build again.
|
||||
|
||||
You can ask the `mach` script to build only changed files:
|
||||
|
||||
@ -66,16 +111,22 @@ Sometimes, if you haven't updated in a while, you'll be told that you need to *c
|
||||
|
||||
```bash
|
||||
./mach clobber
|
||||
./mach build
|
||||
```
|
||||
|
||||
It is a bit tedious to do this manually, but fortunately you can add an entry to `mozconfig` to have this done automatically for you each time it's required. Add this and save the file:
|
||||
|
||||
```
|
||||
# Automatically clobber when an incremental build is not possible
|
||||
mk_add_options AUTOCLOBBER=1
|
||||
```
|
||||
|
||||
### Building even faster with artifact builds
|
||||
|
||||
If you are *not* going to modify any C/C++ code (which is rare when working on DevTools), you can use artifact builds. This method downloads prebuilt binary components, and then the build process becomes faster.
|
||||
It is unusual to modify C/C++ code when working on DevTools. This means that we can use *artifact builds*. This method downloads prebuilt binary components, and then the build process becomes faster.
|
||||
|
||||
Create a file on the root of the repository, called `mozconfig`, with the following content:
|
||||
Add the following content to `mozconfig`:
|
||||
|
||||
```
|
||||
```bash
|
||||
# Automatically download and use compiled C++ components:
|
||||
ac_add_options --enable-artifact-builds
|
||||
|
||||
@ -85,7 +136,7 @@ mk_add_options MOZ_OBJDIR=./objdir-frontend
|
||||
|
||||
And then you can follow the normal build process again (only *faster*!)
|
||||
|
||||
On MacOS you might want to use `MOZ_OBJDIR=./objdir-frontend.noindex` instead. Using the `.noindex` file extension prevents the Spotlight from indexing your `objdir`, which is slow.
|
||||
**Note**: On macOS you might want to use `MOZ_OBJDIR=./objdir-frontend.noindex` instead. Using the `.noindex` file extension prevents the Spotlight from indexing your `objdir`, which is slow.
|
||||
|
||||
For more information on aspects such as technical limitations of artifact builds, read the [Artifact Builds](https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/Artifact_builds) page.
|
||||
|
||||
@ -93,11 +144,13 @@ For more information on aspects such as technical limitations of artifact builds
|
||||
|
||||
Working in DevTools generally involves editing JavaScript files only. This means that often you don't even need to run `./mach build`.
|
||||
|
||||
Instead, what you need to do is to save the files you modified, quit Firefox, and reopen it again to use the recently saved files.
|
||||
Instead, you just need to save the files you modified, and restart Firefox. To achieve this, you *could* quit Firefox, and reopen it again with `./mach run`. Or you could use the `Restart (Developer)` option that is available under the `File` menu in local builds (or its respective shortcut).
|
||||
|
||||
With pseudocode:
|
||||
|
||||
|
||||
```
|
||||
That would be equivalent to the following pseudocode, performed manually:
|
||||
|
||||
```bash
|
||||
# 1. Build
|
||||
./mach build
|
||||
# 2. Run
|
||||
@ -109,6 +162,3 @@ With pseudocode:
|
||||
./mach run
|
||||
```
|
||||
|
||||
While not as fast as the average "save file and reload the website" *web development workflow*, or newer workflows such as React's reloading, this can still be quite fast.
|
||||
|
||||
And certainly faster than building each time, even with artifact builds.
|
||||
|
||||
@ -4,25 +4,35 @@ You can have various [Firefox profiles](https://developer.mozilla.org/en-US/Fire
|
||||
|
||||
This page will guide you through configuring a new profile to enable development features such as additional logging, dumping of network packets, remote debugging, etc. which will help when working in DevTools.
|
||||
|
||||
Many of these changes are achieved by modifying preferences in `about:config`, a special page you can access by entering that in Firefox's URL bar. The first time, it will show you a warning page. Click through and then you can start searching for preferences to modify.
|
||||
Many of these changes are achieved by modifying preferences in `about:config`, a special page you can access by typing in `about:config` in Firefox's URL bar. The first time, it will show you a warning page. Click through or disable the warning for the future, and then you can start searching for preferences to modify.
|
||||
|
||||
Here's [a support article](https://support.mozilla.org/t5/Manage-preferences-and-add-ons/Configuration-Editor-for-Firefox/ta-p/35030) if you need help.
|
||||
(If you're curious, here's more information about [about:config](https://support.mozilla.org/en-US/kb/about-config-editor-firefox))
|
||||
|
||||
## Create a permanent profile
|
||||
|
||||
We were using a temporary profile in the previous step, [building DevTools](./build.md). The contents of this profile are deleted each time the browser is closed, which means any preferences we set will not persist.
|
||||
|
||||
The solution is to create a new profile:
|
||||
The solution is to create a permanent profile:
|
||||
|
||||
```
|
||||
./mach run -P development
|
||||
```
|
||||
|
||||
If this profile doesn't exist yet (quite likely), a window will open offering you options to create a new profile, and asking you which name you want to use. Create a new one, and name it `development`. Then start Firefox by clicking on `Start Nightly`.
|
||||
If this profile doesn't exist yet (quite likely), a window will open offering you options to create a new profile, and asking you for the name you want to use.
|
||||
|
||||
Create a new profile, and name it `development`. Then start Firefox by clicking on `Start Nightly`.
|
||||
|
||||
Next time you start Firefox with `./mach run -P development`, the new profile will be automatically used, and settings will persist between browser launches.
|
||||
|
||||
## Enable additional logging
|
||||
It's now time to [start contributing](../contributing.html)! 😃
|
||||
|
||||
---
|
||||
|
||||
## Advanced settings
|
||||
|
||||
The following section describes how to enable additional development features; don't worry if you don't understand what some of these are or what they're for. Feel free to skip these if you're new; you probably don't need them yet.
|
||||
|
||||
### Enable additional logging
|
||||
|
||||
You can change the value of these preferences by going to `about:config`:
|
||||
|
||||
@ -31,14 +41,16 @@ You can change the value of these preferences by going to `about:config`:
|
||||
| `browser.dom.window.dump.enabled` | `true` | Adds global `dump` function to log strings to `stdout` |
|
||||
| `devtools.console.stdout.chrome` | `true` | Allows console API to write to `stdout` when used by chrome content |
|
||||
| `devtools.console.stdout.content` | `true` | Allows console API to write to `stdout` when used by content |
|
||||
| `devtools.debugger.log` (*) | `true` | Dump packets sent over remote debugging protocol to `stdout`.<br /><br />The [remote protocol inspector add-on](https://github.com/firebug/rdp-inspector/wiki) might be useful too. |
|
||||
| `devtools.debugger.log` (*) | `true` | Dump packets sent over remote debugging protocol to `stdout`.<!-- TODO: I think this is outdated and there isn't a compatible addon anymore <br /><br />The [remote protocol inspector add-on](https://github.com/firebug/rdp-inspector/wiki) might be useful too.--> |
|
||||
| `devtools.dump.emit` (*) | `true` | Log event notifications from the EventEmitter class<br />(found at `devtools/shared/event-emitter.js`). |
|
||||
|
||||
Preferences marked with a (`*`) also require `browser.dom.window.dump.enabled` in order to work. You might not want to enable *all* of those all the time, as they can cause the output to be way too verbose, but they might be useful if you're working on a server actor, for example<!--TODO link to actors doc-->.
|
||||
|
||||
Restart the browser to apply configuration changes.
|
||||
|
||||
## Enable remote debugging and the Browser Toolbox
|
||||
### Enable remote debugging and the Browser Toolbox
|
||||
|
||||
<!--TODO: aren't some of these preferences enabled by default now in local builds? -->
|
||||
|
||||
These settings allow you to use the [browser toolbox](https://developer.mozilla.org/docs/Tools/Browser_Toolbox) to inspect the DevTools themselves, set breakpoints inside of DevTools code, and run the [Scratchpad](https://developer.mozilla.org/en-US/docs/Tools/Scratchpad) in the *Browser* environment.
|
||||
|
||||
@ -55,7 +67,7 @@ In `about:config`, set `devtools.debugger.prompt-connection` to `false`.
|
||||
|
||||
This will get rid of the prompt displayed every time you open the browser toolbox.
|
||||
|
||||
## Enable DevTools assertions
|
||||
### Enable DevTools assertions
|
||||
|
||||
When assertions are enabled, assertion failures are fatal, log console warnings, and throw errors.
|
||||
|
||||
@ -63,7 +75,7 @@ When assertions are not enabled, the `assert` function is a no-op.
|
||||
|
||||
It also enables the "debug" builds of certain third party libraries, such as React.
|
||||
|
||||
To enable assertions, add this to your `.mozconfig`:
|
||||
To enable assertions, add this to your `mozconfig` file:
|
||||
|
||||
```
|
||||
ac_add_options --enable-debug-js-modules
|
||||
@ -76,5 +88,3 @@ const { assert } = require("devtools/shared/DevToolsUtils");
|
||||
// ...
|
||||
assert(1 + 1 === 2, "I really hope this is true...");
|
||||
```
|
||||
|
||||
|
||||
|
||||
BIN
devtools/docs/getting-started/restart.png
Normal file
BIN
devtools/docs/getting-started/restart.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 49 KiB |
Loading…
Reference in New Issue
Block a user