Changes between Initial Version and Version 1 of WatchList

Timestamp:

Oct 19, 2011, 3:01:26 PM (14 years ago)

Author:

levin@chromium.org

Comment:

instructions about using the watch list

WatchList

@@ +1 @@
+The watchlist is a simple way to watch for new patches that interest you.
+
+
+= How to use the watch list =
+
+You’ll need to create a definition which matches patches that you are interested in or find one that already exists. You’ll need to add a rule to cc yourself on the bug (or add a message to the bug).
+
+= Details =
+
+The watchlist file is here: http://trac.webkit.org/browser/trunk/Tools/Scripts/webkitpy/common/config/watchlist
+
+Here’s an example version:
+
+{{{
+{
+    "DEFINITIONS": {
+        "ThreadingFiles": {
+            "filename": r"Source/JavaScriptCore/wtf/ThreadSpecific\."
+                        r"|Source/JavaScriptCore/wtf/ThreadSafeRefCounted\."
+                        
+        },
+        "ThreadingUsage": {
+            "more": r"(CrossThreadCopier|CrossThreadRefCounted)(?!\.(h|cpp))",
+        },
+    },
+    "CC_RULES": {
+        "ThreadingFiles|ThreadingUsage": [ "levin+threading@chromium.org", ],
+    },
+    "MESSAGE_RULES": {
+        "ThreadingUsage": [ "Are you sure you want to using threading?!?", ],
+    },
+}
+}}}
+
+== Definitions section ==
+
+The definitions section is where you define what you want to look for. If it is a filename pattern, use “filename”.  Filename matches are a prefix match.
+
+If is a code pattern use “more” or “less”, if you want to know if more or less of instances in that pattern occur. (more use the regex to find a match modified lines in a patch. Then it searches the to see if more instances of that exact text occur on a per file basis.)  
+
+A definition is said to match if all of its clauses are true for any file in a patch. If you could look for more instances of a pattern occurring only within a group of a files by using both “filename” and “more” together.
+
+== CC rules ==
+
+The cc rules section is where you list who should be added when a definition matches. You can or together definitions but I only recommend doing this when the definitions are highly related.
+
+== Message rules ==
+
+The message rules is where you list any messages that should be added to a bug when a definition matches.
+
+= Trying out your change =
+
+Do a change locally that should trigger your rule and run:
+{{{  webkit-patch apply-watchlist-local }}}
+
+It should tell you who would be cc’ed and any messages that would be added to the bug.
+
+= Check your change for mistakes =
+
+Mistakes will slow things down or mess up your change. Run {{{check-webkit-style}}} on your patch to catch many of these errors.
+
+= Appendix: Details about the regex used in the example: =
+
+One twist in the “more” match is the ?!\.(h|cpp)). This prevents matching mentions of CrossThreadRefCounted.h due to includes, build files, etc. which I don’t care about.
+
+The r is a python thing which means that the \ in the string don’t escape characters (r”\n” is r“\” +”n”) which is handy when you need the \ to escape regex characters.
+
+Python’s regex format is documented here: http://docs.python.org/library/re.html