index.rst (4030B)
1 ========================================== 2 Firefox Welcome Experience (about:welcome) 3 ========================================== 4 5 Files related to the Firefox welcome experience, which includes content that appears on ``about:welcome``, can be found in the ``browser/components/aboutwelcome`` directory. 6 Some of these source files (such as ``.js``, ``.jsx``, and ``.scss``) require an additional build step. 7 We are working on migrating this to work with ``mach``, but in the meantime, please 8 follow the following steps if you need to make changes in this directory: 9 10 For ``.sys.mjs`` files (system modules) 11 --------------------------------------------------- 12 13 No build step is necessary. Use ``mach`` and run mochitests according to your regular Firefox workflow. 14 15 For ``.js``, ``.jsx``, ``.scss``, or ``.css`` files 16 --------------------------------------------------- 17 18 Prerequisites 19 ````````````` 20 21 You will need the following: 22 23 - Node.js 10+ (On Mac, the best way to install Node.js is to use the install link on the `Node.js homepage`_) 24 - npm (packaged with Node.js) 25 26 To install dependencies, run the following from the root of the mozilla-central repository. 27 (Using ``mach`` to call ``npm`` and ``node`` commands will ensure you're using the correct versions of Node and npm.) 28 29 .. code-block:: shell 30 31 (cd browser/components/aboutwelcome && ../../../mach npm install) 32 33 34 Which files should you edit? 35 ```````````````````````````` 36 37 You should not make changes to ``.js`` or ``.css`` files in the ``browser/components/aboutwelcome/content`` directory. Instead, you should edit the ``.jsx``, ``.js``, and ``.scss`` source files 38 in ``browser/components/aboutwelcome/content-src`` directory. These files will be compiled into the ``.js`` and ``.css`` files. 39 40 41 Building assets and running Firefox 42 ----------------------------------- 43 44 To build assets and run Firefox, run the following from the root of the mozilla-central repository: 45 46 .. code-block:: shell 47 48 ./mach npm run bundle --prefix=browser/components/aboutwelcome && ./mach build && ./mach run 49 50 Continuous development / debugging 51 ---------------------------------- 52 Running ``./mach npm run watchmc --prefix=browser/components/aboutwelcome`` will start a process that watches files in 53 ``aboutwelcome`` and rebuilds the bundled files when JS or CSS files change. 54 55 **IMPORTANT NOTE**: This task will add inline source maps to help with debugging, which changes the memory footprint. 56 Do not use the ``watchmc`` task for profiling or performance testing! 57 58 Running tests 59 ------------- 60 About:welcome unit tests are written using 61 `mocha <https://mochajs.org>`_, and other errors that may show up there are 62 `SCSS <https://sass-lang.com/documentation/syntax>`_ issues flagged by 63 `stylelint <https://stylelint.io>`_. These things are all run using 64 ``npm test`` under the ``aboutwelcome`` slug in Treeherder/Try, so if that slug turns 65 red, these tests are what is failing. To execute them, do this: 66 67 .. code-block:: shell 68 69 ./mach npm test --prefix=browser/components/aboutwelcome 70 71 Windows isn't currently supported by ``npm test`` 72 (`path/invocation difference <https://bugzilla.mozilla.org/show_bug.cgi?id=1737419>`_). 73 To run tests that aren't covered by ``mach lint`` and 74 ``mach test``: 75 76 .. code-block:: shell 77 78 ./mach npm run lint:stylelint --prefix=browser/components/aboutwelcome 79 ./mach npm run testmc:build --prefix=browser/components/aboutwelcome 80 ./mach npm run testmc:unit --prefix=browser/components/aboutwelcome 81 82 Mochitests run normally, using ``mach test browser/components/aboutwelcome``. 83 84 Code Coverage 85 ------------- 86 Our testing setup will run code coverage tools in addition to just the unit 87 tests. It will error out if the code coverage metrics don't meet certain thresholds. 88 89 If you see any missing test coverage, you can inspect the coverage report by 90 running 91 92 .. code-block:: shell 93 94 ./mach npm test --prefix=browser/components/aboutwelcome && 95 ./mach npm run debugcoverage --prefix=browser/components/aboutwelcome 96 97 .. _Node.js homepage: https://nodejs.org/