third_party/googletest/README.chromium - cobalt - Git at Google

 Name: Google Test: Google's C++ Testing Framework
 Short Name: googletest
 URL: https://github.com/google/googletest.git
 Version: unknown
 License: BSD
 License File: NOT_SHIPPED
 Security critical: no

 Google Test is imported as-is, to facilitate version bumping. However, the
 file/directory layout of Google Test is not yet considered stable. Therefore,
 until Google Test's layout stabilizes, Chromium code MUST NOT depend on it
 directly. Instead, Chromium code MUST:

 * #include the headers in testing/gtest and testing/gmock
 * use //testing/gtest(:gtest_main) and //testing/gmock(:gmock_main) in BUILD.gn
   deps

 This will allow us to adapt to Google Test changes with minimal disruption.


 ## Resources for Rolling Googletest in Chrome

 ### What is Googletest

 Googletest is an open source C++ testing framework developed by Google and used
 by Chromium. See the [User Guide](https://google.github.io/googletest/).

 ### Where is Googletest

 Googletest is developed in google3 and uses
 [copybara](https://github.com/google/copybara) to sync with the public GitHub
 repository.

 * Development (Googler only): [google3/third\_party/googletest](http://google3/third_party/googletest/)
 * GitHub: https://github.com/google/googletest
 * Chromium mirror: https://chromium.googlesource.com/external/github.com/google/googletest/
 * Locally, [third\_party/googletest/src/](https://source.chromium.org/chromium/chromium/src/+/master:third_party/googletest/src/)
   is a copy of Googletest which is updated via `gclient sync` according to the
   `googletest revision` commit hash in the
   [DEPS file](https://source.chromium.org/chromium/chromium/src/+/master:DEPS;l=244?q=DEPS%20googletest)

 ### Unblocking Googletest Rolls

 1. Roll Googletest to include the breaking change
 * Find the hash (on GitHub) of the offending commit
   * If the change came from google3, the CL number can be found in the
     `PiperOrigin-RevId` footer of Copybara commits
 * On a fresh checkout, pull in the relevant change. Either:
   * Sync using the DEPS file
 ```
 roll-dep --roll-to=commitish src/third_party/googletest/src/
 gclient sync
 ```
   * Check out the commit directly
 ```
 cd third_party/googletest/src
 git remote add up https://github.com/google/googletest.git
 git checkout commitish
 ```

 2. Observe errors
 * Ideally, this can be done by building locally.
   If the build is successful, this means the change does not affect your OS or
   your compiler flags differ from the trybots
 * Upload a CL with the added trybots from
   [Testing Changes to Chromium in Chromium](#testing-changes-to-chromium-in-chromium)

 3. Make changes
 * To Chromium: create a CL including both the roll and other changes
 * To Googletest:
   * Make changes to [third\_party/googletest/src/](https://source.chromium.org/chromium/chromium/src/+/master:third_party/googletest/src/)
     and try building locally. If the fix is successful and you’re confident
     this change will work across all the trybots, create a PR on GitHub or a
     CL to google3 (Googler only) of the changes you made locally to
     [third\_party/googletest/src/](https://source.chromium.org/chromium/chromium/src/+/master:third_party/googletest/src/).
     See [Testing Changes to Googletest in Googletest](#testing-changes-to-googletest-in-googletest)
   * What if I need to make a change to Googletest, but I’m not confident it
     will work with Chromium? Maybe it has to do with a tricky compiler error
     that only affects a specific OS. See
     [Testing Changes to Googletest in Chromium](#testing-changes-to-googletest-in-chromium)
   * Once your Googletest change lands, create a roll which includes both the
     offending commit and your change

 ### Testing Changes to Chromium in Chromium

 Most changes should only require testing via the trybots,
 with the following added:

 `Cq-Include-Trybots: luci.chromium.try:android_optional_gpu_tests_rel;luci.chromium.try:mac_optional_gpu_tests_rel;luci.chromium.try:linux_chromium_cfi_rel_ng;luci.chrome.try:win-chrome`

 ### Testing Changes to Googletest in Googletest

 External: Upload a PR with your proposed changes to GitHub.
 This will trigger automated testing.

 Googlers: See the [Googletest Developer’s Guide](http://go/gunitdev).

 ### Testing Changes to Googletest in Chromium

 In most cases, testing locally with changes to
 [third\_party/googletest/src/](https://source.chromium.org/chromium/chromium/src/+/master:third_party/googletest/src/)
 should be enough. But how can you make sure the changes to Googletest actually
 work in Chromium? Sometimes it’s not possible to test these changes locally
 (different compiler flags, error that only affects a specific OS, etc).
 Insert the pwnall repo:

 * Development: https://github.com/pwnall/googletest
 * Chromium mirror: https://chromium.googlesource.com/external/github.com/pwnall/googletest/

 The pwnall repo allows you to make speculative changes to Googletest and run
 them against the Chromium trybots. The flow is as follows:

 * Create a local remote to the pwnall repo (alternatively, clone it elsewhere):
 ```
 cd third_party/googletest/src
 git remote
 git remote add up https://github.com/google/googletest.git
 git remote add pwnall git@github.com:pwnall/googletest.git
 ```
 * Sync the pwnall repo:
 ```
 git checkout master
 git pull up master
 git push pwnall master
 ```
 * Make changes on a new branch
 * `git push pwnall branch-name`
 * Update the `googletest revision` in the
   [DEPS file](https://source.chromium.org/chromium/chromium/src/+/master:DEPS)
   with the commit hash and `/external/github.com/google/googletest.git` to
   `/external/github.com/pwnall/googletest.git`
 * Upload the CL to run the change against the Chromium trybots

 ### Common Problems

 * Differences in C++ version and clang compiler flags between Chromium and Googletest
   * Chromium is on C++14, though its dependencies,
     which may use Googletest, may be further behind
   * Look for NACL in build errors. You may need to update your GN args with
     `enable_nacl=true` to reproduce these errors locally
 * [A Googletest interface is changed](https://github.com/google/googletest/pull/2718/)
   * Rolling past the commit will fail, since Chromium still uses the old interface
   * Roll past the affecting commit and update uses in Chromium [in one CL](https://crrev.com/c/2709263)
 * [A Googletest header is removed](https://github.com/google/googletest/commit/df6b75949b1efab7606ba60c0f0a0125ac95c5af)
   * Rolling past the commit will fail, since Chromium still expects the header to exist
   * Roll past the affecting commit and updates uses in Chromium [in one CL](https://crrev.com/c/2713029)
 * [A new Googletest feature](https://github.com/google/googletest/commit/ec94d9f24c92a5090fda5567156d6dde99cdbf31)
   requires [updating tests in Chromium](https://crbug.com/1163396#c8)

 ### Other Resources

 * [AutoRoller](https://autoroll.skia.org/r/googletest-chromium-autoroll) and
   accompanying [configuration file](https://skia.googlesource.com/skia-autoroll-internal-config.git/+/main/skia-public/googletest-chromium.cfg)
 * [Bug tracking substantial roll](https://crbug.com/1163396)
	Name: Google Test: Google's C++ Testing Framework
	Short Name: googletest
	URL: https://github.com/google/googletest.git
	Version: unknown
	License: BSD
	License File: NOT_SHIPPED
	Security critical: no

	Google Test is imported as-is, to facilitate version bumping. However, the
	file/directory layout of Google Test is not yet considered stable. Therefore,
	until Google Test's layout stabilizes, Chromium code MUST NOT depend on it
	directly. Instead, Chromium code MUST:

	* #include the headers in testing/gtest and testing/gmock
	* use //testing/gtest(:gtest_main) and //testing/gmock(:gmock_main) in BUILD.gn
	deps

	This will allow us to adapt to Google Test changes with minimal disruption.


	## Resources for Rolling Googletest in Chrome

	### What is Googletest

	Googletest is an open source C++ testing framework developed by Google and used
	by Chromium. See the [User Guide](https://google.github.io/googletest/).

	### Where is Googletest

	Googletest is developed in google3 and uses
	[copybara](https://github.com/google/copybara) to sync with the public GitHub
	repository.

	* Development (Googler only): [google3/third\_party/googletest](http://google3/third_party/googletest/)
	* GitHub: https://github.com/google/googletest
	* Chromium mirror: https://chromium.googlesource.com/external/github.com/google/googletest/
	* Locally, [third\_party/googletest/src/](https://source.chromium.org/chromium/chromium/src/+/master:third_party/googletest/src/)
	is a copy of Googletest which is updated via `gclient sync` according to the
	`googletest revision` commit hash in the
	[DEPS file](https://source.chromium.org/chromium/chromium/src/+/master:DEPS;l=244?q=DEPS%20googletest)

	### Unblocking Googletest Rolls

	1. Roll Googletest to include the breaking change
	* Find the hash (on GitHub) of the offending commit
	* If the change came from google3, the CL number can be found in the
	`PiperOrigin-RevId` footer of Copybara commits
	* On a fresh checkout, pull in the relevant change. Either:
	* Sync using the DEPS file
	```
	roll-dep --roll-to=commitish src/third_party/googletest/src/
	gclient sync
	```
	* Check out the commit directly
	```
	cd third_party/googletest/src
	git remote add up https://github.com/google/googletest.git
	git checkout commitish
	```

	2. Observe errors
	* Ideally, this can be done by building locally.
	If the build is successful, this means the change does not affect your OS or
	your compiler flags differ from the trybots
	* Upload a CL with the added trybots from
	[Testing Changes to Chromium in Chromium](#testing-changes-to-chromium-in-chromium)

	3. Make changes
	* To Chromium: create a CL including both the roll and other changes
	* To Googletest:
	* Make changes to [third\_party/googletest/src/](https://source.chromium.org/chromium/chromium/src/+/master:third_party/googletest/src/)
	and try building locally. If the fix is successful and you’re confident
	this change will work across all the trybots, create a PR on GitHub or a
	CL to google3 (Googler only) of the changes you made locally to
	[third\_party/googletest/src/](https://source.chromium.org/chromium/chromium/src/+/master:third_party/googletest/src/).
	See [Testing Changes to Googletest in Googletest](#testing-changes-to-googletest-in-googletest)
	* What if I need to make a change to Googletest, but I’m not confident it
	will work with Chromium? Maybe it has to do with a tricky compiler error
	that only affects a specific OS. See
	[Testing Changes to Googletest in Chromium](#testing-changes-to-googletest-in-chromium)
	* Once your Googletest change lands, create a roll which includes both the
	offending commit and your change

	### Testing Changes to Chromium in Chromium

	Most changes should only require testing via the trybots,
	with the following added:

	`Cq-Include-Trybots: luci.chromium.try:android_optional_gpu_tests_rel;luci.chromium.try:mac_optional_gpu_tests_rel;luci.chromium.try:linux_chromium_cfi_rel_ng;luci.chrome.try:win-chrome`

	### Testing Changes to Googletest in Googletest

	External: Upload a PR with your proposed changes to GitHub.
	This will trigger automated testing.

	Googlers: See the [Googletest Developer’s Guide](http://go/gunitdev).

	### Testing Changes to Googletest in Chromium

	In most cases, testing locally with changes to
	[third\_party/googletest/src/](https://source.chromium.org/chromium/chromium/src/+/master:third_party/googletest/src/)
	should be enough. But how can you make sure the changes to Googletest actually
	work in Chromium? Sometimes it’s not possible to test these changes locally
	(different compiler flags, error that only affects a specific OS, etc).
	Insert the pwnall repo:

	* Development: https://github.com/pwnall/googletest
	* Chromium mirror: https://chromium.googlesource.com/external/github.com/pwnall/googletest/

	The pwnall repo allows you to make speculative changes to Googletest and run
	them against the Chromium trybots. The flow is as follows:

	* Create a local remote to the pwnall repo (alternatively, clone it elsewhere):
	```
	cd third_party/googletest/src
	git remote
	git remote add up https://github.com/google/googletest.git
	git remote add pwnall git@github.com:pwnall/googletest.git
	```
	* Sync the pwnall repo:
	```
	git checkout master
	git pull up master
	git push pwnall master
	```
	* Make changes on a new branch
	* `git push pwnall branch-name`
	* Update the `googletest revision` in the
	[DEPS file](https://source.chromium.org/chromium/chromium/src/+/master:DEPS)
	with the commit hash and `/external/github.com/google/googletest.git` to
	`/external/github.com/pwnall/googletest.git`
	* Upload the CL to run the change against the Chromium trybots

	### Common Problems

	* Differences in C++ version and clang compiler flags between Chromium and Googletest
	* Chromium is on C++14, though its dependencies,
	which may use Googletest, may be further behind
	* Look for NACL in build errors. You may need to update your GN args with
	`enable_nacl=true` to reproduce these errors locally
	* [A Googletest interface is changed](https://github.com/google/googletest/pull/2718/)
	* Rolling past the commit will fail, since Chromium still uses the old interface
	* Roll past the affecting commit and update uses in Chromium [in one CL](https://crrev.com/c/2709263)
	* [A Googletest header is removed](https://github.com/google/googletest/commit/df6b75949b1efab7606ba60c0f0a0125ac95c5af)
	* Rolling past the commit will fail, since Chromium still expects the header to exist
	* Roll past the affecting commit and updates uses in Chromium [in one CL](https://crrev.com/c/2713029)
	* [A new Googletest feature](https://github.com/google/googletest/commit/ec94d9f24c92a5090fda5567156d6dde99cdbf31)
	requires [updating tests in Chromium](https://crbug.com/1163396#c8)

	### Other Resources

	* [AutoRoller](https://autoroll.skia.org/r/googletest-chromium-autoroll) and
	accompanying [configuration file](https://skia.googlesource.com/skia-autoroll-internal-config.git/+/main/skia-public/googletest-chromium.cfg)
	* [Bug tracking substantial roll](https://crbug.com/1163396)