One tap to privacy Surf, stream, game, and get work done while maintaining your privacy online. Whether you’re traveling, using public WiFi, or simply looking for more online security, we will always put your privacy first.
We encourage you to participate in this open source project. We love Pull Requests, Bug Reports, ideas, (security) code reviews, or any other kind of positive contribution.
Before you attempt to make a contribution please read the Community Participation Guidelines.
Here are some useful links to start:
Moved here -> Dev-Setup
If you want to submit a pull-request, please, install the clang format pre-commit hook that lints code.
The standard conda environment includes the required clang-format libraries.
If the conda environment is not being used, a clang-format library will need
to manually installed. (For example, using Homebrew on macOS:
brew install clang-format
.)
The linter will need to know where to find the clang-format-diff.py
file, so
CLANG_FORMAT_DIFF
must be exported. On a standard conda installation:
export CLANG_FORMAT_DIFF=$(find ~/miniconda3/pkgs -name clang-format-diff.py)
Install the pre-commit hook: ./scripts/git-pre-commit-format install
When built for any one of the desktop platforms, this project will also generate a suite of unit tests.
The tests are built manually specifying the build_tests
target.
cmake --build build --target build_tests -j $(nproc)
Once built, you can run them with ctest
as follows:
ctest --test-dir build -j $(nproc) --output-on-failure
New build required: Functional tests require a dummy build of the application, which is not
built by default. To build the dummyvpn
target, in the root folder of this repository run:
cmake --build build -j$(nproc) --target dummyvpn
This will create a dummy build under the tests/dummyvpn
folder. To run the functional
tests against this build, make sure the MVPN_BIN
environment variable is set:
export MVPN_BIN=$(pwd)/build/tests/dummyvpn/dummyvpn
Other dependencies:
npm install
to install the testing
dependenciesMVPN_BIN
(location of compiled mvpn binary. This must be a dummy binary, see note above.)ARTIFACT_DIR
- optional (directory to put screenshots from test failures)export PATH=$PATH:~/Qt/6.6.3/macos/bin:$PATH
export QT_MACOS_BIN=~/Qt/6.6.3/macos/bin
MVPN_API_BASE_URL=http://localhost:5000
MVPN_BIN=dummybuild/src/mozillavpn
ARTIFACT_DIR=tests/artifact
To run a test: from the root of the project: npm run functionalTest path/to/testFile.js
. To run, say, the authentication tests: npm run functionalTest tests/functional/testAuthenticationInApp.js
.
To enable the staging environment, open the Help
window, and click on the
Help
title text 6 times within 10 seconds to unlock the Developer Options menu.
On this menu, you can enable on the Staging Server
checkbox to switch to the
staging environment. A full restart of the VPN will be required for this option
to take effect.
The inspector is a debugging tool available only when the staging environment
is activated. When running MozillaVPN, go to the inspector page to interact
with the app. Connect the inspector to the app using the web-socket interface.
On desktop, use ws://localhost:8765
.
The inspector offers a number of tools to help debug and navigate through the VPN client:
help
to see the list of available commands.Glean is a Mozilla analytics & telemetry solution that provides a consistent experience and behavior across all of Mozilla products.
When the client is in staging mode, pings will have the app channel set to
staging
. This allows for filtering between staging and production pings through the
client_info.app_channel
metric present in all pings.
Glean provides a series of debug APIs to aid developers and testers in verifying Glean metrics.
These APIs can be accessed through the Mozilla VPN developer menu, under "Telemetry Debugging".
If you are responsible for a piece of work that adds new Glean instrumentation you will need to do a data review. Following is the recommended process along with some pointers.
The data review process is also described here: https://wiki.mozilla.org/Data_Collection
The basic process is this:
data_reviews
entry, that needs to be updated before releasing the new instrumentation and ideally before merging it;data_review
entry on the Glean YAML files.
It must be a public link.Note:
- It is ok for a reviewer to review and approve your code while you're waiting for data review.
- It is not ok to release code that contains instrumentation changes without a data review r+. It is good practice not to merge code that does not have a data review r+.
[^1]: The data-review questionnaire can be found at https://github.com/mozilla/data-review/blob/main/request.md. That can be copy pasted and filled out manually. However,
since the VPN application uses Glean for data collection developers can also use the glean_parser data-review
command,
which generates a mostly filled out data-review questionnaire for Glean users. The questionnaire can seem quite intimidating, but don't panic.
First, look at an old data-review such as https://github.com/mozilla-mobile/mozilla-vpn-client/pull/4594.
Questions 1, 2, 3 an 10 are the ones that require most of your attention and thought.
If you don't know the answers to these questions, reach out to Sarah Bird or the product manager so you can answer these with full confidence.
[^2]: Feel free to ping any of the data-stewards. If the collection is time sensitive consider pinging all data-stewards directly on the data-stewards matrix channel.