morgan/helium
1
0
Fork 0
mirror of https://github.com/morgan9e/helium synced 2026-04-14 00:14:20 +09:00
Code Issues Packages Projects Releases Wiki Activity

repo: update README and remove unrelated upstream docs

Browse Source
This commit is contained in:
wukko
2025-06-13 15:26:41 +06:00
parent 6305ef215f
commit 672c986f28
15 changed files with 25 additions and 893 deletions
Download Patch File Download Diff File Expand all files Collapse all files

101
.github/ISSUE_TEMPLATE/bugreport.yml vendored
View File

@@ -1,101 +0,0 @@
name: Bug Report
description: Report a bug building or running ungoogled-chromium
labels: ["bug"]
body:
- type: markdown
attributes:
value: |
Before submitting this issue, please confirm if you should submit it to a [platform-specific issue tracker instead](https://github.com/ungoogled-software/ungoogled-chromium/blob/master/SUPPORT.md#platform-specific-support)
Otherwise, your issue may not be noticed. In addition, please read through the [SUPPORT.md](https://github.com/ungoogled-software/ungoogled-chromium/blob/master/SUPPORT.md) first
- type: dropdown
id: os
attributes:
label: OS/Platform
description: OS/Platform you are running ungoogled-chromium on
options:
- Android
- Arch Linux
- Debian, Ubuntu, and derivatives
- Fedora and CentOS
- Gentoo
- GNU Guix
- macOS
- NixOS
- Other Linux (please specify)
- Portable Linux
- Slackware
- Windows
validations:
required: true
- type: dropdown
id: install
attributes:
label: Installed
description: How was ungoogled-chromium installed on your OS/Platform
options:
- Compiled from source
- OS/Platform's package manager
- Flatpak
- https://ungoogled-software.github.io/ungoogled-chromium-binaries/
- Other (please use 'Additional context' field below to mention how exactly)
validations:
required: true
- type: input
id: version
attributes:
label: Version
description: ungoogled-chromium version. Could be copied from chrome://settings/help
validations:
required: true
- type: checkboxes
attributes:
label: Have you tested that this is not an upstream issue or an issue with your configuration?
options:
- label: I have tried reproducing this issue in Chrome and it could not be reproduced there
- label: I have tried reproducing this issue in vanilla Chromium and it could not be reproduced there
- label: I have tried reproducing this issue in ungoogled-chromium with a new and empty profile using `--user-data-dir` command line argument and it could not be reproduced there
- type: input
id: description
attributes:
label: Description
description: A clear and concise description (in one line) of what the bug is
validations:
required: true
- type: textarea
id: repro
attributes:
label: How to Reproduce?
description: Steps to reproduce the behaviour
placeholder: |
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error
validations:
required: true
- type: textarea
id: actual
attributes:
label: Actual behaviour
description: A clear and concise description of what happens
validations:
required: true
- type: textarea
id: expected
attributes:
label: Expected behaviour
description: A clear and concise description of what you expected to happen
validations:
required: true
- type: textarea
id: logs
attributes:
label: Relevant log output
description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
render: sh
- type: textarea
id: additional
attributes:
label: Additional context
description: Add any other context about the problem here. If applicable, add screenshots to help explain your problem.

18
.github/ISSUE_TEMPLATE/create-an--updating-to-chromium-x-x-x-x-.md vendored
View File

@@ -1,18 +0,0 @@
---
name: Create an "Updating to Chromium x.x.x.x"
about: For letting the community track progress to a new stable Chromium
title: Updating to Chromium {{ env.VERSION }} on {{ env.PLATFORM }}
labels: update
assignees: ''
---
Chromium stable channel for {{ env.PLATFORM }} has been updated to a newer version: {{ env.VERSION }}.
If you are willing to work on updating the patches and lists, please leave a comment in this issue in order to facilitate better coordination and avoid wasted/duplicated efforts.
If you'd like to increase visibility of your progress or get early feedback/advice, consider creating a [Draft Pull Request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests#draft-pull-requests). Finally, make sure to reference this issue in your PR. Please make sure to read [/docs/developing.md](https://github.com/ungoogled-software/ungoogled-chromium/blob/master/docs/developing.md#updating-patches) for guidance.
Feel free to raise issues or questions throughout the process here. However, please refrain from asking for ETAs unless no visible progress has been made here or in the developer's PR for a while (e.g. 2 weeks).
{{ env.NOTIFY_MAINTAINERS }}

47
.github/ISSUE_TEMPLATE/feature_request.yml vendored
View File

@@ -1,47 +0,0 @@
name: Feature request
description: Suggest an idea
labels: ["enhancement", "help wanted"]
body:
- type: markdown
attributes:
value: |
Before submitting this feature request, please confirm if you should submit it to a [platform-specific issue tracker instead](https://github.com/ungoogled-software/ungoogled-chromium/blob/master/SUPPORT.md#platform-specific-support)
Otherwise, your issue may not be noticed. In addition, please read through the [SUPPORT.md](https://github.com/ungoogled-software/ungoogled-chromium/blob/master/SUPPORT.md) first
- type: input
id: description
attributes:
label: Description
description: A clear and concise description (in one line) of what your suggestion is
validations:
required: true
- type: checkboxes
attributes:
label: Who's implementing?
options:
- label: I'm willing to implement this feature myself
- type: textarea
id: prob
attributes:
label: The problem
description: Please describe the problem you are solving or new feature you're suggesting
placeholder: I'm always frustrated when [...] happens
validations:
required: true
- type: textarea
id: sol
attributes:
label: Possible solutions
description: Please describe possible solution(-s) to The Problem
validations:
required: true
- type: textarea
id: alt
attributes:
label: Alternatives
description: Please describe alternatives you've considered, if any
- type: textarea
id: additional
attributes:
label: Additional context
description: Add any other context about the feature request here

1
.github/PULL_REQUEST_TEMPLATE.md vendored
View File

@@ -1 +0,0 @@
*(Please ensure you have read SUPPORT.md and docs/contributing.md before submitting the Pull Request)*

1
CODEOWNERS
View File

@@ -1 +0,0 @@
* @ungoogled-software/core

197
README.md
View File

@@ -1,185 +1,38 @@
# ungoogled-chromium
# Helium
Bullshit-free web browser, based on Chromium. Follows [imput](https://github.com/imputnet)'s ethics and norms.
*A lightweight approach to removing Google web service dependency*
Very WIP, not meant for public/end user consumption, etc.
**Help is welcome!** See the [docs/contributing.md](docs/contributing.md) document for more information.
First and foremost, we're making a good browser for ourselves.
We don't intend to reinvent the wheel or target everyone, it isn't Helium's goal.
The main goal is to provide an honest, comfortable, privacy-respecting, and non-invasive experience.
If you don't like it - you don't like it, that's totally okay, and we don't care.
## Objectives
There's a lot more to Helium, but we don't have a complete set of features yet.
We'll update the documentation when we're closer to a public release!
In descending order of significance (i.e. most important objective first):
1. **ungoogled-chromium is Google Chromium, sans dependency on Google web services**.
2. **ungoogled-chromium retains the default Chromium experience as closely as possible**. Unlike other Chromium forks that have their own visions of a web browser, ungoogled-chromium is essentially a drop-in replacement for Chromium.
3. **ungoogled-chromium features tweaks to enhance privacy, control, and transparency**. However, almost all of these features must be manually activated or enabled. For more details, see [Feature Overview](#feature-overview).
In scenarios where the objectives conflict, the objective of higher significance should take precedence.
## Content Overview
* [Objectives](#objectives)
* [Motivation and Philosophy](#motivation-and-philosophy)
* [Feature Overview](#feature-overview)
* [**Downloads**](#downloads)
* [Source Code](#source-code)
* [**FAQ**](#faq)
* [Building Instructions](#building-instructions)
* [Design Documentation](#design-documentation)
* [**Contributing, Reporting, Contacting**](#contributing-reporting-contacting)
* [Credits](#credits)
* [Related Projects](#related-projects)
* [License](#license)
## Motivation and Philosophy
Without signing in to a Google Account, Chromium does pretty well in terms of security and privacy. However, Chromium still has some dependency on Google web services and binaries. In addition, Google designed Chromium to be easy and intuitive for users, which means they compromise on transparency and control of internal operations.
ungoogled-chromium addresses these issues in the following ways:
1. Remove all remaining background requests to any web services while building and running the browser
2. Remove all code specific to Google web services
3. Remove all uses of pre-made binaries from the source code, and replace them with user-provided alternatives when possible.
4. Disable features that inhibit control and transparency, and add or modify features that promote them (these changes will almost always require manual activation or enabling).
These features are implemented as configuration flags, patches, and custom scripts. For more details, consult the [Design Documentation](docs/design.md).
## Feature Overview
*This section overviews the features of ungoogled-chromium. For more detailed information, it is best to consult the source code.*
Contents of this section:
* [Key Features](#key-features)
* [Enhancing Features](#enhancing-features)
* [Borrowed Features](#borrowed-features)
* [Supported Platforms and Distributions](#supported-platforms-and-distributions)
### Key Features
*These are the core features introduced by ungoogled-chromium.*
* Disable functionality specific to Google domains (e.g. Google Host Detector, Google URL Tracker, Google Cloud Messaging, Google Hotwording, etc.)
* This includes disabling [Safe Browsing](https://en.wikipedia.org/wiki/Google_Safe_Browsing). Consult [the FAQ for the rationale](https://ungoogled-software.github.io/ungoogled-chromium-wiki/faq#why-is-safe-browsing-disabled).
* Block internal requests to Google at runtime. This feature is a fail-safe measure for the above, in case Google changes or introduces new components that our patches do not disable. This feature is implemented by replacing many Google web domains in the source code with non-existent alternatives ending in `qjz9zk` (known as domain substitution; [see docs/design.md](docs/design.md#source-file-processors) for details), then [modifying Chromium to block its own requests with such domains](patches/core/ungoogled-chromium/block-trk-and-subdomains.patch). In other words, no connections are attempted to the `qjz9zk` domain.
* Strip binaries from the source code (known as binary pruning; [see docs/design.md](docs/design.md#source-file-processors) for details)
### Enhancing Features
*These are the non-essential features introduced by ungoogled-chromium.*
* Add many new command-line switches and `chrome://flags` entries to configure new features (which are disabled by default). See [docs/flags.md](docs/flags.md) for the exhaustive list.
* Add *Suggestions URL* text field in the search engine editor (`chrome://settings/searchEngines`) for customizing search engine suggestions.
* Add more URL schemes allowed to save page schemes.
* Add Omnibox search provider "No Search" to allow disabling of searching
* Add a custom cross-platform build configuration and packaging wrapper for Chromium. It currently supports many Linux distributions, macOS, and Windows. (See [docs/design.md](docs/design.md) for details on the system.)
* Force all pop-ups into tabs
* Disable automatic formatting of URLs in Omnibox (e.g. stripping `http://`, hiding certain parameters)
* Disable intranet redirect detector (extraneous DNS requests)
* This breaks captive portal detection, but captive portals still work.
* (Iridium Browser feature change) Prevent URLs with the `trk:` scheme from connecting to the Internet
* Also prevents any URLs with the top-level domain `qjz9zk` (as used in domain substitution) from attempting a connection.
* (Windows-specific) Do not set the Zone Identifier on downloaded files
### Borrowed Features
In addition to the features introduced by ungoogled-chromium, ungoogled-chromium selectively borrows many features from the following projects (in approximate order of significance):
* [Inox patchset](https://github.com/gcarq/inox-patchset)
* [Bromite](https://github.com/bromite/bromite)
* [Debian](https://tracker.debian.org/pkg/chromium)
* [Iridium Browser](https://iridiumbrowser.de/)
### Supported Platforms and Distributions
[See docs/platforms.md for a list of supported platforms](docs/platforms.md).
Other platforms are discussed and tracked in this repository's Issue Tracker. Learn more about using the Issue Tracker under the section [Contributing, Reporting, Contacting](#contributing-reporting-contacting).
## Downloads
### Automated or maintained builds
ungoogled-chromium is available in the following **software repositories**:
* Arch: Available in the AUR, [see instructions in ungoogled-chromium-archlinux](https://github.com/ungoogled-software/ungoogled-chromium-archlinux)
* Debian & Ubuntu: Available in OBS, find your [distribution specific instructions](https://github.com/ungoogled-software/ungoogled-chromium-debian) in the Installing section
* Fedora: Available in [COPR](https://copr.fedorainfracloud.org/coprs/) as [`wojnilowicz/ungoogled-chromium`](https://copr.fedorainfracloud.org/coprs/wojnilowicz/ungoogled-chromium/). Also available in [RPM Fusion](https://rpmfusion.org/Configuration) as `chromium-browser-privacy` (outdated).
* Gentoo: Available in [`::pf4public`](https://github.com/PF4Public/gentoo-overlay) overlay as [`ungoogled-chromium`](https://github.com/PF4Public/gentoo-overlay/tree/master/www-client/ungoogled-chromium) and [`ungoogled-chromium-bin`](https://github.com/PF4Public/gentoo-overlay/tree/master/www-client/ungoogled-chromium-bin) ebuilds
* [OpenMandriva](https://openmandriva.org/) includes ungoogled-chromium as its main browser. The `chromium` package includes all ungoogling patches.
* macOS: Available in [Homebrew](https://brew.sh/) as [`eloston-chromium`](https://formulae.brew.sh/cask/eloston-chromium). Just run `brew install --cask eloston-chromium`. Chromium will appear in your `/Applications` directory.
* FreeBSD: Available in pkg as [`www/ungoogled-chromium`](https://www.freshports.org/www/ungoogled-chromium/).
If your GNU/Linux distribution is not listed, there are distro-independent builds available via the following **package managers**:
* Flatpak: Available [in the Flathub repo](https://flathub.org/apps/details/io.github.ungoogled_software.ungoogled_chromium) as `io.github.ungoogled_software.ungoogled_chromium`
* GNU Guix: Available as `ungoogled-chromium`
* NixOS/nixpkgs: Available as `ungoogled-chromium`
### Third-party binaries
If your operating system is not listed above, you can also try to [**Download binaries from here**](https://ungoogled-software.github.io/ungoogled-chromium-binaries/)
*NOTE: These binaries are provided by anyone who are willing to build and submit them. Because these binaries are not necessarily [reproducible](https://reproducible-builds.org/), authenticity cannot be guaranteed; In other words, there is always a non-zero probability that these binaries may have been tampered with. In the unlikely event that this has happened to you, please [report it in a new issue](#contributing-reporting-contacting).*
These binaries are known as **contributor binaries**.
## Source Code
This repository only contains the common code for all platforms; it does not contain all the configuration and scripts necessary to build ungoogled-chromium. Most users will want to use platform-specific repos, where all the remaining configuration and scripts are provided for specific platforms:
[**Find the repo for a specific platform here**](docs/platforms.md).
If you wish to include ungoogled-chromium code in your own build process, consider using [the tags in this repo](https://github.com/ungoogled-software/ungoogled-chromium/tags). These tags follow the format `{chromium_version}-{revision}` where
* `chromium_version` is the version of Chromium used in `x.x.x.x` format, and
* `revision` is a number indicating the version of ungoogled-chromium for the corresponding Chromium version.
Additionally, most platform-specific repos extend their tag scheme upon this one.
**Building the source code**: [See docs/building.md](docs/building.md)
### Mirrors
List of mirrors:
* [Codeberg](https://codeberg.org): [main repo](https://codeberg.org/ungoogled-software/ungoogled-chromium) and [ungoogled-software](https://codeberg.org/ungoogled-software)
## FAQ
[See the frequently-asked questions (FAQ) on the Wiki](https://ungoogled-software.github.io/ungoogled-chromium-wiki/faq)
## Building Instructions
[See docs/building.md](docs/building.md)
## Design Documentation
[See docs/design.md](docs/design.md)
## Contributing, Reporting, Contacting
* For reporting and contacting, see [SUPPORT.md](SUPPORT.md)
* If you're willing to help, check out the [Issue Tracker](https://github.com/ungoogled-software/ungoogled-chromium/issues) and especially issues, which [need help](https://github.com/ungoogled-software/ungoogled-chromium/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22)
* For contributing (e.g. how to help, submitting changes, criteria for new features), see [docs/contributing.md](docs/contributing.md)
* If you have some small contributions that don't fit our criteria, consider adding them to [ungoogled-software/contrib](https://github.com/ungoogled-software/contrib) or [our Wiki](https://github.com/ungoogled-software/ungoogled-chromium-wiki) instead.
## Platform-specific packaging
At the moment, we're only working on [Helium for macOS](https://github.com/imputnet/helium-macos).
We plan to create packaging for Windows & Linux systems in the future, but that's over the horizon for now.
## Credits
### ungoogled-chromium
Helium is proudly based on [ungoogled-chromium](https://github.com/ungoogled-software/ungoogled-chromium).
It wouldn't be possible for us to get rid of Google's bloat and get a development+building pipeline this fast without it.
Huge shout-out to everyone behind this amazing project!
(and we intend to contribute even more stuff upstream in the future)
* [The Chromium Project](https://www.chromium.org/)
* [Inox patchset](https://github.com/gcarq/inox-patchset)
* [Debian](https://tracker.debian.org/pkg/chromium-browser)
* [Bromite](https://github.com/bromite/bromite)
* [Iridium Browser](https://iridiumbrowser.de/)
* The users for testing and debugging, [contributing code](https://github.com/ungoogled-software/ungoogled-chromium/graphs/contributors), providing feedback, or simply using ungoogled-chromium in some capacity.
### The Chromium project
[The Chromium Project](https://www.chromium.org/) is obviously at the core of Helium,
making it possible to exist in the first place.
## Related Projects
List of known projects that fork or use changes from ungoogled-chromium:
* [Bromite](https://github.com/bromite/bromite) (Borrows some patches. Features builds for Android)
* [ppc64le fork](https://github.com/leo-lb/ungoogled-chromium) (Fork with changes to build for ppc64le CPUs)
### ungoogled-chromium's dependencies
- [Inox patchset](https://github.com/gcarq/inox-patchset)
- [Debian](https://tracker.debian.org/pkg/chromium-browser)
- [Bromite](https://github.com/bromite/bromite)
- [Iridium Browser](https://iridiumbrowser.de/)
## License
All code, patches, modified portions of imported code or patches, and
any other content that is unique to Helium and not imported from other
repositories is licensed under GPL-3.0. See [LICENSE](LICENSE).

30
SUPPORT.md
View File

@@ -1,30 +0,0 @@
# Support
**Before you submit feedback, please ensure you have tried the following**:
* Read the [FAQ](https://ungoogled-software.github.io/ungoogled-chromium-wiki/faq)
* If you are using a build for an officially-supported platform ([see the list here](docs/platforms.md)), then please refer to the [Platform-specific Support](#platform-specific-support) section first.
* Check if your feedback already exists in the [Issue Tracker](https://github.com/ungoogled-software/ungoogled-chromium/issues) (make sure to search closed issues and use search filters, as applicable)
* If this is a problem, ensure it does *not* occur with regular Chromium or Google Chrome. If it does, then this is *not* a problem with ungoogled-chromium. Instead, please submit your feedback to the [Chromium bug tracker](https://bugs.chromium.org/p/chromium/issues/list) or Google.
* Read the documentation under [docs/](docs/)
There are a few channels for support:
* An issue tracker. Issue trackers are the main hubs for discussions and development activity, and thus the primary means of support. They includes problems, suggestions, and questions. If you are using a build for an officially-supported platform ([see the list here](docs/platforms.md)), then please refer to the [Platform-specific Support](#platform-specific-support) section to find its issue tracker. Otherwise, please use [the main issue tracker](https://github.com/ungoogled-software/ungoogled-chromium/issues).
* A chat room. There are two options available:
* [Gitter](https://gitter.im/ungoogled-software/Lobby). It can use your GitHub account as an identity.
* Matrix.org under name `ungoogled-software/lobby`. It has a bidirectional connection with Gitter.
## Platform-specific Support
For officially-supported platforms, **please visit their issue trackers before using the issue tracker in this repository**:
* Android: [Issue tracker](https://github.com/ungoogled-software/ungoogled-chromium-android/issues)
* Arch Linux and derivatives (e.g. Manjaro): [Issue tracker](https://github.com/ungoogled-software/ungoogled-chromium-archlinux/issues)
* Debian & Ubuntu: [Issue tracker](https://github.com/ungoogled-software/ungoogled-chromium-debian/issues)
* Fedora & CentOS: [Issue tracker](https://github.com/ungoogled-software/ungoogled-chromium-fedora/issues)
* Flatpak: [Issue tracker](https://github.com/ungoogled-software/ungoogled-chromium-flatpak/issues)
* Gentoo ([@PF4Public](https://github.com/PF4Public)'s overlay): [Issue tracker](https://github.com/PF4Public/gentoo-overlay/issues?q=is%3Aissue++ungoogled-chromium+)
* macOS: [Issue tracker](https://github.com/ungoogled-software/ungoogled-chromium-macos/issues)
* Portable Linux: [Issue tracker](https://github.com/ungoogled-software/ungoogled-chromium-portablelinux/issues)
* Windows: [Issue tracker](https://github.com/ungoogled-software/ungoogled-chromium-windows/issues)

76
docs/building.md
View File

@@ -1,76 +0,0 @@
# Building ungoogled-chromium
The recommended way to build ungoogled-chromium is by consulting [the repository for your supported platform (links here)](platforms.md).
* *Linux users*: If your distribution is not listed, you will need to use Portable Linux.
If you want to add ungoogled-chromium to your existing Chromium build process, see the next section. Additionally, you may reference the repositories for supported platforms for inspiration.
## Integrating ungoogled-chromium into your Chromium build process
Typically, ungoogled-chromium is built from [code in platform-specific repositories](platforms.md). However, ungoogled-chromium can also be included in part or in whole into any custom Chromium build. In this section, **we will assume you already have a process to make your own Chromium builds**.
**NOTE**: You may need additional patches and/or build configuration for [your supported platform](platforms.md) because this repository does not contain all the code necessary for all platforms.
Before continuing, you may find it helpful to have a look through [the design documentation](design.md).
The following procedure outline the essential steps to build Chromium will all of ungoogled-chromium's features. **They are not sufficient to build ungoogled-chromium on their own**.
1. Ensure Chromium is downloaded, such as by `depot_tools`. In most of our supported platforms, we instead use a custom tool to do this.
```sh
mkdir -p build/download_cache
./utils/downloads.py retrieve -c build/download_cache -i downloads.ini
./utils/downloads.py retrieve -c build/download_cache -i extras.ini
./utils/downloads.py unpack -c build/download_cache -i downloads.ini -- build/src
./utils/downloads.py unpack -c build/download_cache -i extras.ini -- build/src
```
2. Prune binaries
```sh
./utils/prune_binaries.py build/src pruning.list
```
3. Apply patches
```sh
./utils/patches.py apply build/src patches
```
4. Substitute domains and names
```sh
./utils/domain_substitution.py apply -r domain_regex.list -f domain_substitution.list -c build/domsubcache.tar.gz build/src
python3 ./utils/name_substitution.py" --sub -t build/src
```
5. Build GN. If you are using `depot_tools` to checkout Chromium or you already have a GN binary, you should skip this step.
```sh
mkdir -p build/src/out/Default
cd build/src
./tools/gn/bootstrap/bootstrap.py --skip-generate-buildfiles -j4 -o out/Default/
```
6. Invoke the build:
```
mkdir -p build/src/out/Default
# NOTE: flags.gn contains only a subset of what is needed to run the build.
cp flags.gn build/src/out/Default/args.gn
cd build/src
# If you have additional GN flags to add, make sure to add them now.
./out/Default/gn gen out/Default --fail-on-unused-args
ninja -C out/Default chrome chromedriver chrome_sandbox
```
## Building FAQ
### My build keeps crashing because I run out of RAM! How can I fix it?
Here are several ways to address this, in decreasing order of preference:
1. Decrease the number of parallel threads to Ninja (the `-j` flag)
2. Add swap space

52
docs/contributing.md
View File

@@ -1,52 +0,0 @@
# Contributing
This document contains our criteria and guidelines for contributing to ungoogled-chromium.
If you have **small contributions that don't fit our criteria**, consider adding them to [ungoogled-software/contrib](https://github.com/ungoogled-software/contrib) or [our Wiki](https://github.com/ungoogled-software/ungoogled-chromium-wiki) instead.
If you are a developer of an **officially-supported platform**, be sure to check out the [Platform Repository Standards and Guidelines](repo_management.md).
List of contents:
* [How to help](#how-to-help)
* [Submitting changes](#submitting-changes)
* [Criteria for new features](#criteria-for-new-features)
### How to help
Generally, ungoogled-chromium needs contributors to help:
* Keep up-to-date with the latest stable Chromium, and any problematic changes in the new version that needs modification.
* Help with issues marked with the `help wanted` tag (usually either questions for other users, or request for help from other developers)
* Review Pull Requests from other contributors
* Implement feature requests ("enhancements" in the Issue Tracker), large or small.
* Implement issues marked with the `backlog` tag (that are closed).
* If it requires new code, please read through the [Submitting changes](#submitting-changes) section below.
In addition, anyone is free to help others in need of support in the Issue Tracker.
If there are fixes, tweaks, or additions you want to make, continue onto the following section.
### Submitting changes
Please submit all changes via Pull Requests.
Guidelines:
* You are welcome to submit minor changes, such as bug fixes, documentation fixes, and tweaks.
* If your change has an associated issue, please let others know that you are working on it.
* If you want to submit a new feature, please read through the [Criteria for new features](#criteria-for-new-features) below.
* When in doubt about the acceptance of a change, you are welcome to ask via an issue first.
### Criteria for new features
1. New features should not detract from the default Chromium experience, unless it falls under the project's main objectives (i.e. removing Google integration and enhancing privacy).
* For larger features, please propose them via an issue first.
2. New features should live behind a setting that is **off by default**.
* Settings are usually added via a command-line flag and `chrome://flags` entries. See [the relevant section in docs/developing.md](developing.md#adding-command-line-flags-and-chromeflags-options) for more information.
* Unless there are significant benefits, adding the setting to `chrome://settings` is *not recommended* due to the additional maintenance required (caused by the infrastructure that backs preferences).
**NOTE**: In the event that the codebase changes significantly for a non-essential patch (i.e. a patch that does not contribute to the main objectives of ungoogled-chromium), it will be removed until someone updates it.

20
docs/default_settings.md
View File

@@ -1,20 +0,0 @@
# Default Settings
Vanilla Chromium settings are not often changed by ungoogled-chromium, however there are some exceptions.
Below is a list of the documented changes to the default Chromium settings.
Setting | New State | Location
-- | -- | --
Allow sites to check if you have payment methods saved | Disabled | chrome://settings/payments
Ask where to save each file before downloading | Enabled | chrome://settings/downloads
Auto sign-in | Disabled | chrome://settings/passwords
Block third-party cookies | Enabled | chrome://settings/cookies
Continue running background apps when Chromium is closed | Disabled | chrome://settings/system
Hyperlink auditing (\<a ping>) | Disabled | NA
Link Doctor | Disabled | NA
Offer to save passwords | Disabled | chrome://settings/passwords
Payment autofill | Disabled | chrome://settings/payments
Preload pages | Disabled | chrome://settings/cookies
Search suggestions | Disabled | chrome://settings/syncSetup
Show bookmark bar | Enabled | chrome://settings/appearance
WebRTC IP handling policy | Disable Non-Proxied UDP | `--webrtc-ip-handling-policy`

118
docs/design.md
View File

@@ -1,118 +0,0 @@
# Design
This document contains a high-level technical description of ungoogled-chromium and its components.
## Overview
ungoogled-chromium consists of the following major components:
* [Configuration](#configuration)
* [Configuration files](#configuration-files)
* [Source file processors](#source-file-processors)
* [Patches](#patches)
* [Packaging](#packaging)
The following sections describe each component.
## Configuration
Configuration is a broad term that refers to patches, build flags, and metadata about Chromium source code. It consists of the following components:
* [Configuration files](#configuration-files)
* [Source file processors](#source-file-processors)
* [Patches](#patches)
The following sections describe each component in more depth.
### Configuration Files
Configuration files (or config files) are files that store build configuration and source code changes for a build.
**IMPORTANT**: For consistency, all config files must be encoded in UTF-8.
List of configuration files:
* `chromium_version.txt` - The Chromium version used by ungoogled-chromium
* `revision.txt` - The revision of the changes on top of the given Chromium version.
* `pruning.list` - [See the Source File Processors section](#source-file-processors)
* `domain_regex.list` - [See the Source File Processors section](#source-file-processors)
* `domain_substitution.list` - [See the Source File Processors section](#source-file-processors)
* `downloads.ini` - Archives to download and unpack into the buildspace tree. This includes code not bundled in the Chromium source code archive that is specific to a non-Linux platform. On platforms such as macOS, this also includes a pre-built LLVM toolchain for convenience (which can be removed and built from source if desired).
* `flags.gn` - GN arguments to set before building.
### Source File Processors
Source file processors are utilities that directly manipulate the Chromium source tree before building. Currently, there are two such utilities: binary pruning, and domain substitution.
**Binary Pruning**: Strips binaries from the source code. This includes pre-built executables, shared libraries, and other forms of machine code. Most are substituted with system or user-provided equivalents, or are built from source; those binaries that cannot be removed do not contain machine code.
The list of files to remove are determined by the config file `pruning.list`. This config file is generated by `devutils/update_lists.py`.
**Domain Substitution**: Replaces Google and several other web domain names in the Chromium source code with non-existent alternatives ending in `qjz9zk`. These changes are mainly used as a backup measure to detect potentially unpatched requests to Google. Note that domain substitution is a crude process, and *may not be easily undone*.
With a few patches from ungoogled-chromium, any requests with these domain names sent via `net::URLRequest` in the Chromium code are blocked and notify the user via a info bar.
Similar to binary pruning, the list of files to modify are listed in `domain_substitution.list`; it is also updated with `devutils/update_lists.py`.
The regular expressions to use are listed in `domain_regex.list`; the search and replacement expressions are delimited with a pound (`#`) symbol. The restrictions for the entries are as follows:
* All replacement expressions must end in the TLD `qjz9zk`.
* The search and replacement expressions must have a one-to-one correspondence: no two search expressions can match the same string, and no two replacement expressions can result in the same string.
### Patches
All of ungoogled-chromium's patches for the Chromium source code are located in `patches/`. This directory conforms to the default GNU Quilt format. That is:
* All patches must reside inside `patches/`
* There is a `patches/series` text file that defines the order to apply all the patches. These patches are listed as a relative path from the `patches` directory.
* Lines starting with the pound symbol (`#`) are ignored
* For lines with patch paths: If there is a space followed by a pound symbol, the text after the patch path will be ignored.
All patch files in ungoogled-chromium must satisfy these formatting requirements:
* Patch filenames must end with the extension `.patch`
* The content must be in [unified format](https://en.wikipedia.org/wiki/Diff_utility#Unified_format).
* All paths in the hunk headers must begin after the first slash (which corresponds to the argument `-p1` for GNU patch).
* All patches must apply cleanly (i.e. no fuzz).
* It is recommended that hunk paths have the `a/` and `b/` prefixes, and a context of 3 (like the git default).
* All patches must be encoded in UTF-8 (i.e. same encoding as config files).
Patches are categorized into two directories directly under `patches/`:
1. **core**: Changes regarding background requests, code specific to Google web services, or code using pre-made binaries. They must be kept up-to-date with all of the changes in Chromium.
2. **extra**: Changes to features regarding control and transparency. They are not guaranteed to persist across updates to Chromium.
Within each category, patches are grouped by the following:
* `debian/` - Patches from Debian's Chromium
* Patches are not modified unless they conflict with Inox's patches
* These patches are not Debian-specific. For those, see the `debian/patches` directory
* `inox-patchset/` - Contains a modified subset of patches from Inox patchset.
* Some patches such as those that change branding are omitted
* Patches are not modified unless they do not apply cleanly onto the version of Chromium being built
* Patches are from [inox-patchset's GitHub](https://github.com/gcarq/inox-patchset)
* [Inox patchset's license](https://github.com/gcarq/inox-patchset/blob/master/LICENSE)
* `bromite/` - Patches from [Bromite](https://github.com/bromite/bromite)
* `iridium-browser/` - Contains a modified subset of patches from Iridium Browser.
* Some patches such as those that change branding or URLs to point to Iridium's own servers are omitted
* Patches are not modified unless they conflict with Debian's or Inox's patches
* Patches are from the `patchview` branch of Iridium's Git repository. [Git webview of the patchview branch](https://git.iridiumbrowser.de/cgit.cgi/iridium-browser/?h=patchview)
* `opensuse/` - Patches from openSUSE's Chromium
* `ubuntu/` - Patches from Ubuntu's Chromium
* `ungoogled-chromium/` - Patches by ungoogled-chromium developers
## Packaging
Packaging is the process of downloading, building, and producing a distributable package of ungoogled-chromium.
Packaging files use the code from this repository to build ungoogled-chromium. Each platform and configuration has an associated packaging repository under the [ungoogled-software](https://github.com/ungoogled-software) organization. For more information about each packaging repository, see the [building documentation](building.md).
Packaging generally consists of the major steps:
1. Download and unpack the source tree
2. Prune binaries
3. Apply patches
4. Substitute domains
5. Build GN via `tools/gn/bootstrap/bootstrap.py`
6. Run `gn gen` with the GN flags
7. Build Chromium via `ninja`
8. Create package(s) of build output (usually in `out/Default`)

90
docs/developing.md
View File

@@ -1,90 +0,0 @@
# Development notes and procedures
This document contains an assortment of information for those who want to develop ungoogled-chromium.
Information targeted towards developers *and* other users live in [the Wiki](https://ungoogled-software.github.io/ungoogled-chromium-wiki/).
Contents:
* [Branches](#branches)
* [Adding command-line flags and chrome://flags options](#adding-command-line-flags-and-chromeflags-options)
* [Workflow of updating to a new Chromium version](#workflow-of-updating-to-a-new-chromium-version)
## Branches
Development is focused on `master`, and any changes in there should not break anything unless platforms break during a Chromium version rebase.
Larger feature changes or hotfixes must be done in a separate branch. Once they are ready, then a Pull Request can be made onto `master` (for contributors with write access, merging directly via a git client is fine). After the branch is merged, it should be removed.
## Adding command-line flags and `chrome://flags` options
See `docs/how_to_add_your_feature_flag.md` in the Chromium source tree for the steps needed. Note that updating `tools/metrics/histograms/enums.xml` is not required.
For new flags, first add a constant to `third_party/ungoogled/ungoogled_switches.cc` (by modifying patch `resources/patches/ungoogled-chromium/add-third-party-ungoogled.patch`). Then, use this constant in the steps outlined above.
## Workflow of updating to a new Chromium version
Tested on Debian 10 (buster). Exact instructions should work on any other Linux or macOS system with the proper dependencies.
To gain a deeper understanding of this updating process, have a read through [docs/design.md](design.md).
### Dependencies
* [`quilt`](http://savannah.nongnu.org/projects/quilt)
* This is available in most (if not all) Linux distributions, and also Homebrew on macOS.
* This utility facilitates most of the updating process, so it is important to learn how to use this. The manpage for quilt (as of early 2017) lacks an example of a workflow. There are multiple guides online, but [this guide from Debian](https://wiki.debian.org/UsingQuilt) and [the referenced guide on that page](https://raphaelhertzog.com/2012/08/08/how-to-use-quilt-to-manage-patches-in-debian-packages/) are the ones referenced in developing the current workflow.
* Python 3.9 or newer
* `httplib2` and `six` are also required if you wish to utilize a source clone instead of the source tarball.
### Downloading the source code
```sh
./utils/clone.py -o build/src
```
### Updating lists
The utility `devutils/update_lists.py` automates this process. By default, it will update the files in the local repo. Pass in `-h` or `--help` for available options.
```sh
./devutils/update_lists.py -t build/src
```
The resulting source tree in `build/src` *will not* have binaries pruned or domains substituted.
### Updating patches
**IMPORTANT**: Make sure domain substitution has not been applied before updating patches.
1. Run `source devutils/set_quilt_vars.sh` (or `source devutils/set_quilt_vars.fish` if you are using the fish shell)
* This will setup quilt to modify patches directly in `patches/`
2. Go into the source tree: `cd build/src`
3. Use `quilt` to refresh all patches: `quilt push -a --refresh`
* If an error occurs, go to the next step. Otherwise, skip to Step 5.
4. Use `quilt` to fix the broken patch:
1. Run `quilt push -f`
2. Edit the broken files as necessary by adding (`quilt edit ...` or `quilt add ...`) or removing (`quilt remove ...`) files as necessary
* When removing large chunks of code, remove each line instead of using language features to hide or remove the code. This makes the patches less susceptible to breakages when using quilt's refresh command (e.g. quilt refresh updates the line numbers based on the patch context, so it's possible for new but desirable code in the middle of the block comment to be excluded.). It also helps with readability when someone wants to see the changes made based on the patch alone.
3. Refresh the patch: `quilt refresh`
4. Go back to Step 3.
5. Run `quilt pop -a`
6. Go back to ungoogled-chromium repo: `cd ../..`
7. Run `devutils/validate_config.py`. If any warnings are printed, address them; otherwise, continue to Step 8.
8. Run `devutils/validate_patches.py -l build/src`. If errors occur, go back to Step 3.
This should leave unstaged changes in the git repository to be reviewed, added, and committed.
### Steps for fixing patches after a failed build attempt
If domain substitution is not applied, then the steps from the previous section will work for revising patches.
If domain substitution is applied, then the steps for the initial update will not apply since that would create patches which depend on domain substitution. Here is a method of dealing with this:
1. Revert domain substitution: `./utils/domain_substitution.py revert -c CACHE_PATH_HERE build/src`
2. Follow the patch updating section above
3. Reapply domain substitution: `./utils/domain_substitution.py apply -r domain_regex.list -f domain_substitution.list -c CACHE_PATH_HERE build/src`
4. Reattempt build. Repeat steps as necessary.
### Next steps
* Submit a Pull Request of these changes to the ungoogled-chromium repo.
* Once the PR is merged, update the repositories of each platform repository that you are maintaining under the `ungoogled-software` organization.

100
docs/flags.md
View File

@@ -1,100 +0,0 @@
# List of flags and switches
This is an exhaustive list of command-line switches and flags introduced by ungoogled-chromium.
Each switch has a corresponding entry on the `chrome://flags` page which can be filtered by searching for `ungoogled-chromium`.
If a switch requires a value, you must specify it with an `=` sign; e.g. flag `--foo` with value `bar` should be written as `--foo=bar`.
> **NOTE**: If you add a command-line argument that is also in `chrome://flags`, the flag's state will not be indicated in `chrome://flags`. There is no universal way to ensure command-line flags are taking effect, but you can find if they're being seen by checking `chrome://version`.
- ### Available on all platforms
<code>Switch&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code> | Description
-- | --
`--disable-beforeunload` | Disables JavaScript dialog boxes triggered by `beforeunload`
`--disable-grease-tls` | Disables GREASE for TLS. Combined with `--http-accept-header` allows browser to look more like a tor-browser. See https://github.com/ungoogled-software/ungoogled-chromium/issues/783 for more details.
`--disable-search-engine-collection` | Disable automatic search engine scraping from webpages.
`--extension-mime-request-handling` | Change how extension MIME types (CRX and user scripts) are handled. Acceptable values are `download-as-regular-file` or `always-prompt-for-install`. Leave unset to use normal behavior.
`--fingerprinting-canvas-image-data-noise` | (Added flag to Bromite feature) Implements fingerprinting deception for Canvas image data retrieved via JS APIs. In the data, at most 10 pixels are slightly modified.
`--fingerprinting-canvas-measuretext-noise` | (Added flag to Bromite feature) Scale the output values of Canvas::measureText() with a randomly selected factor in the range -0.0003% to 0.0003%, which are recomputed on every document initialization.
`--fingerprinting-client-rects-noise` | (Added flag to Bromite feature) Implements fingerprinting deception of JS APIs `getClientRects()` and `getBoundingClientRect()` by scaling their output values with a random factor in the range -0.0003% to 0.0003%, which are recomputed for every document instantiation.
`--force-punycode-hostnames` | Convert all Internationalized Domain Names to punycode (ASCII representation of Unicode). See https://github.com/ungoogled-software/ungoogled-chromium/issues/370 for more details.
`--hide-crashed-bubble` | Hides the bubble box with the message "Restore Pages? Chromium didn't shut down correctly." that shows on startup after the browser did not exit cleanly.
`--http-accept-header` | Changes the default value of the `Accept` HTTP header sent with HTTP requests. Combined with `--disable-grease-tls` allows browser to look more like a tor-browser. See https://github.com/ungoogled-software/ungoogled-chromium/issues/783 for more details.
`--keep-old-history` | Disables deletion of local browser history after 90 days
`--max-connections-per-host` | (from Bromite) Configure the maximum allowed connections per host. Valid values are `6` and `15`
`--omnibox-autocomplete-filtering` | Restrict omnibox autocomplete results to a combination of search suggestions (if enabled), bookmarks, and internal chrome pages. Accepts `search`, `search-bookmarks`, `search-chrome`, and `search-bookmarks-chrome`.
`--popups-to-tabs` | Makes popups open in new tabs.
- ### Available only on desktop
<code>Switch&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code> | Description
-- | --
`--bookmark-bar-ntp` | Sets the visibility of the bookmark bar on the New Tab Page. Only takes the value `never`.
`--close-confirmation` | Show a warning prompt when closing the browser window. Accepts `last` (prompt when closing the last window with several tabs) and `multiple` (prompt only if more than one window is open).
`--close-window-with-last-tab` | Determines whether a window should close once the last tab is closed. Only takes the value `never`.
`--custom-ntp` | Allows setting a custom URL for the new tab page. Value can be internal (e.g. `about:blank` or `chrome://new-tab-page`), external (e.g. `example.com`), or local (e.g. `file:///tmp/startpage.html`). This applies for incognito windows as well when not set to a `chrome://` internal page.
`--disable-sharing-hub` | Disables the sharing hub button.
`--enable-incognito-themes` | Allows themes to change the appearance of Incognito windows.
`--hide-extensions-menu` | Hides the extensions container. This includes the puzzle piece icon as well as any pinned extensions.
`--hide-fullscreen-exit-ui` | Hides the "X" that appears when the mouse cursor is moved towards the top of the window in fullscreen mode. Additionally, this hides the "Press F11 to exit full screen" popup.
`--hide-tab-close-buttons` | Hides the close buttons on tabs.
`--remove-grab-handle` | Removes the reserved empty space in the tabstrip for moving the window.
`--remove-tabsearch-button` | Removes the tabsearch button from the tabstrip.
`--scroll-tabs` | Determines if scrolling will cause a switch to a neighboring tab if the cursor hovers over the tabs, or the empty space beside the tabs. The flag requires one the values: `always`, `never`, `incognito-and-guest`. When omitted, the default is to use platform-specific behavior, which is currently enabled only on desktop Linux.
`--show-avatar-button` | Sets visibility of the avatar button. The flag requires one of the values: `always`, `incognito-and-guest` (only show Incognito or Guest modes), or `never`.
`--tab-hover-cards` | Allows removing the tab hover cards or using a tooltip as a replacement. This can be set with the values `none` or `tooltip`.
- #### Available only on Windows
<code>Switch&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code> | Description
-- | --
`--disable-encryption` | Disable encryption of cookies, passwords, and settings which uses a generated machine-specific encryption key. This is used to enable portable user data directories.
`--disable-machine-id` | Disables use of a generated machine-specific ID to lock the user data directory to that machine. This is used to enable portable user data directories.
## Feature flags
Feature flags are similar to switches with the difference being that they are passed as values for the `--enable-features` switch. Multiple features can be passed at the same time by separating them with a comma, e.g. `--enable-features=flag1,flag2,flag3`.
These are also available on the `chrome://flags` page.
- ### Available on all platforms
Feature | Description
-- | --
`MinimalReferrers` | Removes all cross-origin referrers and strips same-origin referrers down to the origin. Has lower precedence than `NoCrossOriginReferrers`.
`NoCrossOriginReferrers` | Removes all cross-origin referrers. Has lower precedence than `NoReferrers`.
`NoReferrers` | Removes all referrers.
`ReducedSystemInfo` | Reduces the amount of system information obatainable through headers and javascript, also causes hardwareConcurrency to respond with two cores.
`RemoveClientHints` | Removes client hints (information sent to servers about your system, similar to a user agent).
`SetIpv6ProbeFalse` | Forces the result of the browser's IPv6 probing (i.e. IPv6 connectivity test) to be unsuccessful. This causes IPv4 addresses to be prioritized over IPv6 addresses. Without this flag, the probing result is set to be successful, which causes IPv6 to be used over IPv4 when possible.
`SpoofWebGLInfo` | Return generic values for WebGLDebugRendererInfo to remove a potential data leak while preventing potential website breakage.
- ### Available only on desktop
Feature | Description
-- | --
`ClearDataOnExit` | Clears all browsing data on exit.
`DisableLinkDrag` | Prevents dragging of links and selected text. Allows selecting text from a middle of a link. Also allows starting selection without first clearing the existing one. This behaviour is similar to the one from older Opera. See https://github.com/ungoogled-software/ungoogled-chromium/pull/2080 and https://github.com/ungoogled-software/ungoogled-chromium/discussions/2055 for more information.
`DisableQRGenerator` | Disables the QR generator for sharing page links.
## Flags for existing switches
Chromium contains switches that do no have corresponding entries in `chrome://flags`. For convenience, ungoogled-chromium has created entries for some of the commonly-used switches.
- ### Available on all platforms
<code>Switch&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code> | Description
-- | --
`--disable-top-sites` | Disables the top sites and most visited entries on the new tab page.
`--disable-webgl` | Disable all versions of WebGL.
`--enable-low-end-device-mode` | Force low-end device mode when set.
`--force-dark-mode` | Forces dark mode in UI for platforms that support it.
`--no-default-browser-check` | Disables the default browser check.
`--no-pings` | Don't send hyperlink auditing pings.
`--webrtc-ip-handling-policy` | Restrict which IP addresses and interfaces WebRTC uses.
- ### Available only on desktop
<code>Switch&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code> | Description
-- | --
`--incognito` | Start in Incognito.
`--start-maximized` | Starts the browser maximized, regardless of any previous settings.

11
docs/platforms.md
View File

@@ -1,11 +0,0 @@
# Supported Platforms
This page lists platforms officially supported by ungoogled-chromium, and their associated repositories.
* Android: [ungoogled-chromium-android](https://github.com/ungoogled-software/ungoogled-chromium-android)
* Arch Linux: [ungoogled-chromium-archlinux](https://github.com/ungoogled-software/ungoogled-chromium-archlinux)
* Debian, Ubuntu, and derivatives: [ungoogled-chromium-debian](https://github.com/ungoogled-software/ungoogled-chromium-debian)
* Fedora and CentOS: [ungoogled-chromium-fedora](https://github.com/ungoogled-software/ungoogled-chromium-fedora)
* Portable Linux (for any Linux distro): [ungoogled-chromium-portablelinux](https://github.com/ungoogled-software/ungoogled-chromium-portablelinux)
* Windows: [ungoogled-chromium-windows](https://github.com/ungoogled-software/ungoogled-chromium-windows)
* macOS: [ungoogled-chromium-macos](https://github.com/ungoogled-software/ungoogled-chromium-macos)

56
docs/repo_management.md
View File

@@ -1,56 +0,0 @@
# Platform Repository Standards and Guidelines
*This document is new, and its structure and content may change. If you have suggestions, please create an issue!*
ungoogled-chromium is comprised of anonymous developers who volunteer their efforts. Some of these developers may choose to provide long-term support for [an officially-supported platform](platforms.md), or bring support to a new platform. For such developers, this document consists of standards and management guidelines for platform repos.
We will refer to this git repository as "the main repo", and refer to repositories that add platform-specific code to build ungoogled-chromium as "platform repos". An "officially-supported platform" is a platform with a platform repo in [the ungoogled-software organization](https://github.com/ungoogled-software) and noted in [docs/platforms.md](platforms.md).
## Standards
An officially-supported platform repo:
* Must not modify or remove existing patches, GN flags, domain substitution, or binary pruning in the main repo. Instead, you can add new patches or add more files/rules to domain substitution or binary pruning. (If you think a change is needed in the main repo, please make an issue!)
* Must have a tagging/versioning scheme that includes the ungoogled-chromium version.
* Must not require an Internet connection during compilation (before compilation is OK).
* Should allow the user to download all build requirements before building.
* Must not require external services to build, aside from repos in the ungoogled-software organization and repos provided by or used by Chromium.
* Should have a reproducible build for all versions (currently, there is no formal process to enforce/verify reproducibility of binaries)
Each deviation must be clearly noted in the platform repo's documentation (such as the repo's README), and have an associated issue in the platform repo.
## Teams in the ungoogled-software organization
Each officially-supported platform has one or more teams in the ungoogled-software organization. These teams provide additional means for collaborating with other developers, such as issue triaging and private discussions (see section "How to communicate" below).
If you are a regular contributor and would like to provide long-term support for a platform, you can request to be included in the ungoogled-software organization team for your platform. Since the number of developers is low, there is no formal process to do this; just ask in an issue.
## How to communicate
In the interest of transparency, it is recommended to discuss work in public spaces like issues or PRs. If a discussion should not involve outsiders, you can lock the issue or PR to collaborators only.
You must use team discussions if you are discussing or sharing information that can affect the security of the repository. Otherwise, you may use team discussions at your discretion.
## Issues
Each platform repo should have a team in ungoogled-software with the Triage permission level. All members should feel free to manage issues.
TODO: More details?
## Pull Requests
TODO
## Repository Settings and Shared Resources
Shared resources includes:
* CI services like CirrusCI, GitHub Actions, etc.
* Build services like OpenSUSE Build Service (OBS)
These need to be handled with care, as they can cause a wide variety of issues from security and privacy leaks all the way to data loss.
There are several ways to handle shared resources:
* Assign one person to manage a certain set of settings (i.e. grant them "ownership" of those settings). If you want to change a setting, you should request a change in a team discussion.
* TODO: More ways to manage settings?