[#227] Add docs for set_job_description and update the changelog

Author: riley-harper

hlink/linking/util.py

@@ -21,6 +21,12 @@ def spark_shuffle_partitions_heuristic(dataset_size: int) -> int:
 
 @contextmanager
 def set_job_description(desc: str | None, spark_context):
+    """Set the Spark job description.
+
+    This context manager sets the Spark job description to the given string,
+    then restores the job description to its previous value on exit. Passing
+    desc=None resets the job description to the Spark default.
+    """
     previous_desc = spark_context.getLocalProperty("spark.job.description")
     spark_context.setJobDescription(desc)
     try:

sphinx-docs/changelog.md

@@ -3,6 +3,14 @@
 The format of this changelog is based on [Keep A Changelog][keep-a-changelog].
 Hlink adheres to semantic versioning as much as possible.
 
+## Not Yet Released
+
+### Added
+
+* Started setting custom Spark job descriptions for some of hlink's long-running
+  jobs. These descriptions appear in the Spark UI and make it easier to understand
+  what hlink is doing. [PR #228][pr228]
+
 ## v4.2.1 (2025-08-18)
 
 ### Fixed
@@ -453,6 +461,7 @@ and false negative data in model exploration. [PR #1][pr1]
 [pr215]: https://github.com/ipums/hlink/pull/215
 [pr219]: https://github.com/ipums/hlink/pull/219
 [pr222]: https://github.com/ipums/hlink/pull/222
+[pr228]: https://github.com/ipums/hlink/pull/228
 
 [household-matching-docs]: config.html#household-matching
 [household-training-docs]: config.html#household-training-and-model-exploration