diff --git a/relnotes/next b/relnotes/next
--- a/relnotes/next
+++ b/relnotes/next
@@ -21,4 +21,31 @@
 
 == Internal API Changes ==
 
+The Dirstate API have been updated, the previous function leaked some internal
+details and did not distinct between two importan cases: "We are changing
+parent and need to adjust the dirstate" and "some command is changing which
+file is tracked"
 
+To clarify the situation, the following function have been deprecated:
+
+- dirstate.add
+- dirstate.normal
+- dirstate.normallookup
+- dirstate.merge
+- dirstate.otherparent
+- dirstate.remove
+- dirstate.drop
+
+And theses new functions are added for the "adjusting parent" use-case:
+
+- dirstate.update_file
+- dirstate.update_file_p1
+
+And theses new function are added for the "adjusting wc file" use-case":
+
+- dirstate.set_tracked
+- dirstate.set_untracked
+- dirstate.set_clean
+- dirstate.set_possibly_dirty
+
+See inline documentation of the new functions for details.