fix: insert_marker= is now start_marker= #77

Author: nedbat

changelog.d/20250419_192659_nedbat_title_in_template.rst

@@ -16,9 +16,10 @@
 Changed
 .......
 
-- The ``output_file`` setting is now called ``changelog`` since some uses of
-  scriv only read the file.  An ``output_file`` entry in the config file will
-  still work to set the name.  Closes `issue 77`_.
+- Two settings have new names to better reflect what scriv does.
+  The ``output_file`` setting is now called ``changelog`` and the
+  ``insert_marker`` setting is now called ``start_marker``.
+  The old names will continue to work.  Closes `issue 77`_.
 
 .. _issue 77: https://github.com/nedbat/scriv/issues/77
 

docs/commands.rst

@@ -139,7 +139,7 @@ the new entry with the ``--title`` option.
 The output file is specified by the :ref:`config_changelog` setting.  Scriv
 looks in the file for a special marker (usually in a comment) to determine
 where to insert the new entry.  The marker is "scriv-insert-here", but can be
-changed with the :ref:`config_insert_marker` setting.  Using a marker like
+changed with the :ref:`config_start_marker` setting.  Using a marker like
 this, you can have your changelog be just part of a larger README file.  If
 there is no marker in the file, the new entry is inserted at the top of the
 file.

docs/configuration.rst

@@ -306,17 +306,6 @@ The scriv configuration is available in a ``{{config}}`` object.
 Default: ``{{body}}``
 
 
-.. _config_insert_marker:
-
-insert_marker
--------------
-
-A marker string indicating where in the changelog file new
-entries should be inserted.
-
-Default: ``scriv-insert-here``
-
-
 .. _config_main_branches:
 
 main_branches
@@ -373,6 +362,18 @@ not be collected.
 Default: ``README.*``
 
 
+.. _config_start_marker:
+
+start_marker
+------------
+
+A marker string indicating where in the changelog file new
+entries should be inserted.  The old name for this setting is
+:ref:`insert_marker <deprecated_config>`.
+
+Default: ``scriv-insert-here``
+
+
 .. _config_version:
 
 version
@@ -385,7 +386,7 @@ source file.
 
 Default: (empty)
 
-.. [[[end]]] (checksum: acce6a163b5e8567a695069a8b5146e3)
+.. [[[end]]] (checksum: 1b528f5aa913cecca1337c5dda4aa206)
 
 
 .. _deprecated_config:
@@ -397,6 +398,7 @@ Some names in the config file have been updated. The old names will continue to
 work, but the new names are preferred:
 
 - ``output_file`` is now ``changelog``.
+- ``insert_marker`` is now ``start_marker``.
 
 
 .. _git_settings:

src/scriv/changelog.py

@@ -60,7 +60,7 @@ def read(self) -> None:
                     else:
                         self.newline = f.newlines[0]
             before, marker, after = partition_lines(
-                changelog_text, self.config.insert_marker
+                changelog_text, self.config.start_marker
             )
             if marker:
                 self.text_before = before + marker

src/scriv/config.py

@@ -83,13 +83,14 @@ class _Options:
         },
     )
 
-    insert_marker = attr.ib(
+    start_marker = attr.ib(
         type=str,
         default="scriv-insert-here",
         metadata={
             "doc": """\
                 A marker string indicating where in the changelog file new
-                entries should be inserted.
+                entries should be inserted.  The old name for this setting is
+                :ref:`insert_marker <deprecated_config>`.
                 """,
         },
     )
@@ -223,6 +224,13 @@ class _Options:
     )
 
 
+# Map of old config names to new config names.
+REPLACED_NAMES = [
+    ("output_file", "changelog"),
+    ("insert_marker", "start_marker"),
+]
+
+
 @contextlib.contextmanager
 def validator_exceptions():
     """
@@ -333,7 +341,8 @@ def read_one_config(self, configfile: str) -> None:
             scriv_data = parser[section_name]
             for attrdef in attr.fields(_Options):
                 self.get_set_option(scriv_data, attrdef.name, attrdef.name)
-            self.get_set_option(scriv_data, "output_file", "changelog")
+            for old, new in REPLACED_NAMES:
+                self.get_set_option(scriv_data, old, new)
 
     def read_one_toml(self, tomlfile: str) -> None:
         """
@@ -368,7 +377,8 @@ def read_one_toml(self, tomlfile: str) -> None:
                 return
             for attrdef in attr.fields(_Options):
                 self.get_set_option(scriv_data, attrdef.name, attrdef.name)
-            self.get_set_option(scriv_data, "output_file", "changelog")
+            for old, new in REPLACED_NAMES:
+                self.get_set_option(scriv_data, old, new)
 
     def resolve_value(self, value: str) -> str:
         """

src/scriv/format_md.py

@@ -16,7 +16,7 @@ def parse_text(
 
         # If there's an insert marker, start there.
         for lineno, line in enumerate(lines):
-            if self.config.insert_marker in line:
+            if self.config.start_marker in line:
                 lines = lines[lineno + 1 :]
                 break
 

src/scriv/format_rst.py

@@ -59,7 +59,7 @@ def parse_text(
 
         # If there's an insert marker, start there.
         for lineno, line in enumerate(lines):
-            if self.config.insert_marker in line:
+            if self.config.start_marker in line:
                 lines = lines[lineno + 1 :]
                 break
         lines.append("")

tests/test_changelog.py

@@ -70,7 +70,7 @@
 )
 def test_round_trip(text, temp_dir):
     path = temp_dir / "foo.rst"
-    config = Config(insert_marker="INSERT", end_marker="END")
+    config = Config(start_marker="INSERT", end_marker="END")
     path.write_text(text)
     changelog = Changelog(path, config)
     changelog.read()

tests/test_config.py

@@ -15,9 +15,12 @@
 [scriv]
 changelog = README.md
 categories = New, Different, Gone, Bad
+start_marker = FIRST!
 """
 
-OLD_CONFIG1 = CONFIG1.replace("changelog = ", "output_file = ")
+OLD_CONFIG1 = CONFIG1.replace("changelog = ", "output_file = ").replace(
+    "start_marker = ", "insert_marker = "
+)
 
 CONFIG2 = """\
 [someotherthing]
@@ -68,14 +71,17 @@
     "Gone",
     "Bad",
 ]
+start_marker = "FIRST!"
 # other scriv options
 
 ["more stuff"]
 value = 17
 """
 )
 
-OLD_TOML_CONFIG = TOML_CONFIG.replace("changelog = ", "output_file = ")
+OLD_TOML_CONFIG = TOML_CONFIG.replace("changelog = ", "output_file = ").replace(
+    "start_marker = ", "insert_marker = "
+)
 
 
 def test_defaults(temp_dir):
@@ -95,7 +101,7 @@ def test_defaults(temp_dir):
         "Security",
     ]
     assert config.changelog == "CHANGELOG.rst"
-    assert config.insert_marker == "scriv-insert-here"
+    assert config.start_marker == "scriv-insert-here"
     assert config.rst_header_chars == "=-"
     assert config.md_header_level == "1"
     assert "{{ date.strftime('%Y-%m-%d') }}" in config.entry_title_template
@@ -111,6 +117,7 @@ def test_reading_config(config_text, temp_dir):
     assert config.fragment_directory == "changelog.d"
     assert config.changelog == "README.md"
     assert config.categories == ["New", "Different", "Gone", "Bad"]
+    assert config.start_marker == "FIRST!"
 
 
 def test_reading_config_list(temp_dir):
@@ -323,6 +330,7 @@ def test_reading_toml_file(self, config_text, temp_dir):
         config = Config.read()
         assert config.changelog == "README.md"
         assert config.categories == ["New", "Different", "Gone", "Bad"]
+        assert config.start_marker == "FIRST!"
 
     def test_toml_without_us(self, temp_dir):
         (temp_dir / "pyproject.toml").write_text(GENERIC_TOML_CONFIG)