[Suggestions category] Warn more about removing categories.

components/ntp_snippets/category.h

 // Copyright 2016 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef COMPONENTS_NTP_SNIPPETS_CATEGORY_H_
 #define COMPONENTS_NTP_SNIPPETS_CATEGORY_H_
 
 #include <ostream>
 
 namespace ntp_snippets {
@@ skipping 15 matching lines @@
   DOWNLOADS,
 
   // Recently used bookmarks.
   BOOKMARKS,
 
   // Physical Web page available in the vicinity.
   PHYSICAL_WEB_PAGES,
 
   // Pages recently browsed to on other devices.
   FOREIGN_TABS,
-  // INSERT NEW LOCAL CATEGORIES HERE!
+
+  // ****************** INSERT NEW LOCAL CATEGORIES HERE! ******************
+  // Existing categories must never be removed. This happens easily if you
+  // switch out of a local branch that contains a new category. If you cannot
+  // avoid it, consider forcing ConstantCategoryRanker via chrome://flags.
+  // Otherwise, Chrome will crash and you would need to reinstall it to fix it.

[vitaliii, 2017/02/08 08:40:35]

Jumping directly to "switching out of a local branch" seems premature. This is
just one example of "removing a category implicitly", I would like to point this
out explicitly instead of an example. Also "switching out of a branch" does not
cause this by itself, you also need to install the app, so this is very indirect
way of saying what is going on.
I do not like giving advice on how to avoid this. There may be other places
where this information is persisted, so this comment is likely to become
outdated (and misleading). Also this is not Android-only code, so I am not sure
whether "Chrome will crash" is always true.

Overall, I would go for:

" Existing categories are persisted and they must never be removed. This may
happen implicitly, e.g. when an older version without some local category is
installed. "

As for development, you can make a parent branch with your new category and make
all other branches depend on it. Or you probably could temporarily add your
category as remote.

[jkrcal, 2017/02/08 10:12:05]

Done.

 
   // Follows the last local category.
   LOCAL_CATEGORIES_COUNT,
 
   // Remote categories come after this.
   REMOTE_CATEGORIES_OFFSET = 10000,
 
   // Articles for you.
   ARTICLES,
-  // INSERT NEW REMOTE CATEGORIES HERE!
+
+  // ****************** INSERT NEW REMOTE CATEGORIES HERE! ******************
 
   // Tracks the last known remote category
   LAST_KNOWN_REMOTE_CATEGORY = ARTICLES,
 };
 
 // A category groups ContentSuggestions which belong together. Use the
 // CategoryFactory to obtain instances.
 class Category {
  public:
   // An arbitrary but consistent ordering. Can be used to look up categories in
@@ skipping 41 matching lines @@
 
 struct Category::CompareByID {
   bool operator()(const Category& left, const Category& right) const;
 };
 
 std::ostream& operator<<(std::ostream& os, const Category& obj);
 
 }  // namespace ntp_snippets
 
 #endif  // COMPONENTS_NTP_SNIPPETS_CATEGORY_H_