docs/modifying_session_history_serialization.md
Note: Please expand these steps as needed. See also NavigationEntryImpl comments for how to save and restore values outside of PageState, which is less common.
The following (non-exhaustive) steps are required to add new values to the PageState data serialization process, which is used for saving and restoring values in session restore across different versions of Chromium, as well as tab restore and tab duplication within a running instance of Chromium.
Note that changing the serialization format is high risk and should be approached carefully. Mistakes or missed steps can cause backwards compatibility problems, because the effects can continue to live on disk between different versions of Chromium. For this reason, it is important to make these changes carefully, minimizing the risk of reverts (e.g., not as part of much larger CLs) or other back-and-forth between formats (e.g., not as part of an A/B experiment).
Please ask the CL reviewer to also consult this checklist to ensure no steps have been missed.
RecursivelyGenerateFrameEntries
and
RecursivelyGenerateFrameState
in content/browser/renderer_host/navigation_entry_impl.cc to save and
restore the new value from appropriate locations in Chromium.content/browser/renderer_host/frame_navigation_entry.h, indicating if the
new value is persisted if necessary (e.g.
here).third_party/blink/public/mojom/page_state/page_state.mojom,
following the current instructions and warnings in the comments. These
include (but are not limited to):
Next MinVersion
in the comments and increment it.Next Ordinal
value for that section. Include [MinVersion=<N>] in front of the
mojom declaration for the newly added value. E.g. if adding a value to
ExplodedFrameState, update the Next Ordinal value for the struct FrameState section.ExplodedFrameState
in
third_party/blink/public/common/page_state/page_state_serialization.h.kCurrentVersion
in third_party/blink/common/page_state/page_state_serialization.cc, and
modify the comment above to explain what’s new in this version.WriteFrameState
and
ReadFrameState
functions in third_party/blink/common/page_state/page_state_serialization.cc
to save and restore the new value in the persistence format.ExplodedFrameState::assign()
to copy the new element so that its copy constructor and assignment operator
works as expected.ExplodedFrameState-specialization of
ExpectEquality()
in third_party/blink/common/page_state/page_state_serialization_unittest.cc.PopulateFrameStateForBackwardsCompatTest,
for cases where the version value equals/exceeds the new kCurrentVersion
set earlier.PopulateFrameState
to include the newly-added value.TEST_F(PageStateSerializationTest, BackwardsCompat_v<NN>), where <NN>
is replaced by the new kCurrentVersion value.third_party/blink/common/page_state/test_data/serialized_v<NN>.dat, using
the following steps:
third_party/blink/common/page_state/page_state_serialization_unittest.cc,
find the
#if 0
directive before TEST_F(PageStateSerializationTest, DumpExpectedPageStateForBackwardsCompat), and temporarily change it to
#if 1.blink_common_unittests then run with
--gtest_filter=PageStateSerializationTest.DumpExpectedPageStateForBackwardsCompatexpected.dat in the temp directory (e.g.
/tmp on Linux). Copy this file to
third_party/blink/common/page_state/test_data/serialized_v<NN>.dat
and run git add.#if 1 change made to
page_state_serialization_unittest.cc above once the new baseline data
has been created.