Added a change-log: new file, v1.0.0_changelog.md - #467
Conversation
added, deleted, or changed (classes and functions) in the RustWorkX migration effort.
…frm_rustworkx_post_alpha
peterrrock2
left a comment
peterrrock2
left a comment
There was a problem hiding this comment.
Thank you for putting this together! It looks like this still contains many of the generation artifacts from the diff script, so the next step is to pare this down. Would you mind doing the following:
- Remove the “Internal functions” section after moving any user-facing changes out of it. Also remove the file-by-file headings, emojis, and raw generated-diff language.
- Group related entries under subjects such as Graphs, randomness and reproducibility, Markov chains, ReCom, partitions, and optimization.
- Link to the migration and reproducibility guides for detailed instructions if warranted.
- Recheck removals, please. The comparison script is not designed to track inheritance, properties, exports, or file moves, so it has falsely flagged a couple of things. For example,
Assignment.items(),keys(), andvalues()remain available throughMapping, andtree.pywas reorganized into a package, so the file is gone butgerrychain.treeis still a valid import path. - Include constructor changes even though the methods are named init. In particular, the MarkovChain, optimizer, constraint, election, and tally constructor changes are public API changes.
Here is a super short example that should give you a better idea of what I mean:
Added
Markov chains
- Added incremental configuration through
add_constraint(),
add_updater(), and related methods.Graphs
- Added methods for converting between GerryChain, NetworkX, and
RustworkX graphs.- Added
node_data()andedge_data()for accessing graph attributes
(note: this replaces NetworkX-style indexed access).ReCom proposals
- Added ready-made proposal builders under the
ReComnamespace.- Added support for multi-member ReCom.
Changed
Graphno longer subclassesnetworkx.Graph. Node and edge data
access has changed. See the v1.0 migration guide.- GerryChain now uses independent random number generators configured
throughrng=. See the reproducibility guide.
I'll finalize the "Deprecated" and "Removed" sections after the compatibility shims are in.
As for where to put this, let's rename this file to "CHANGELOG.md" and leave it at the repo root. We should be able to expose it in the documentation navigation so that we do not need to maintain two copies.
|
OK - I will do this tomorrow.
However I am still not clear what you want
For instance, who is the audience? Is it the same audience as the migration
guide or is it for gerrychain developers? That is, users vs contributors?
What level of detail do you want? For instance do you want changes in
parameters and parameter names or is that too detailed?
…On Wed, Jul 29, 2026 at 7:20 PM Peter ***@***.***> wrote:
***@***.**** requested changes on this pull request.
Thank you for putting this together! It looks like this still contains
many of the generation artifacts from the diff script, so the next step is
to pare this down. Would you mind doing the following:
- Remove the “Internal functions” section after moving any user-facing
changes out of it. Also remove the file-by-file headings, emojis, and raw
generated-diff language.
- Group related entries under subjects such as Graphs, randomness and
reproducibility, Markov chains, ReCom, partitions, and optimization.
- Link to the migration and reproducibility guides for detailed
instructions if warranted.
- Recheck removals, please. The comparison script is not designed to
track inheritance, properties, exports, or file moves, so it has falsely
flagged a couple of things. For example, Assignment.items(), keys(),
and values() remain available through Mapping, and tree.py was
reorganized into a package, so the file is gone but gerrychain.tree is
still a valid import path.
- Include constructor changes even though the methods are named *init*.
In particular, the MarkovChain, optimizer, constraint, election, and tally
constructor changes are public API changes.
Here is a super short example that should give you a better idea of what I
mean:
Added Markov chains
- Added incremental configuration through add_constraint(),
add_updater(), and related methods.
Graphs
- Added methods for converting between GerryChain, NetworkX, and
RustworkX graphs.
- Added node_data() and edge_data() for accessing graph attributes
(note: this replaces NetworkX-style indexed access).
ReCom proposals
- Added ready-made proposal builders under the ReCom namespace.
- Added support for multi-member ReCom.
Changed
- Graph no longer subclasses networkx.Graph. Node and edge data
access has changed. See the v1.0 migration guide
<http://docs/topics/v1p0p0_migration_guide.md>.
- GerryChain now uses independent random number generators configured
through rng=. See the reproducibility guide
<http://docs/topics/reproducibility.md>.
I'll finalize the "Deprecated" and "Removed" sections after the
compatibility shims are in.
As for where to put this, let's rename this file to "CHANGELOG.md" and
leave it at the repo root. We should be able to expose it in the
documentation navigation so that we do not need to maintain two copies.
—
Reply to this email directly, view it on GitHub
<#467?email_source=notifications&email_token=AAVB2BFMMB5MSJBKFH3FWSD5HKBD3A5CNFSNUABKM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UKJSXM2LFO4XTIOBRGM3TEMJVGMZ2M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KYZTPN52GK4S7MNWGSY3L#pullrequestreview-4813721533>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAVB2BGRUJZNAWWEHLQNMDL5HKBD3AVCNFSNUABFKJSXA33TNF2G64TZHMYTGNRWHAZTMOJWHNEXG43VMU5TKMBRGI3TQOJYHAZ2C5QC>
.
Triage notifications, keep track of coding agent tasks and review pull
requests on the go with GitHub Mobile for iOS
<https://github.com/notifications/mobile/ios/AAVB2BC3CCOF2IGFA6XF6RD5HKBD3A5CNFSNUABKM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UKJSXM2LFO4XTIOBRGM3TEMJVGMZ2M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KUZTPN52GK4S7NFXXG>
and Android
<https://github.com/notifications/mobile/android/AAVB2BF534KLGYN5KXWI7QT5HKBD3A5CNFSNUABKM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UKJSXM2LFO4XTIOBRGM3TEMJVGMZ2M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2K4ZTPN52GK4S7MFXGI4TPNFSA>.
Download it today!
You are receiving this because you authored the thread.Message ID:
***@***.***>
|
|
OK - I have taken a second pass. My guess is that it is still not quite what you want, but hopefully it is much closer. Work left to be done:
|
|
Oh - I pushed the changes so you should see them. Also - on the TODO list - I don't know where to put this once it is finished. |
peterrrock2
left a comment
peterrrock2
left a comment
There was a problem hiding this comment.
This is very close to ready. Responses to a couple of your questions:
... who is the audience? Is it the same audience as the migration guide or is it for gerrychain developers? That is, users vs contributors?
The migration guide is for normal users, and the CHANGELOG will be targeting "super" users.
What level of detail do you want? For instance do you want changes in parameters and parameter names or is that too detailed?
This CHANGELOG should be thorough, but terse. Users should be able to ctrl+f to find information, but the prose should be limited to only what is strictly necessary to understand the change. So, sentence fragments are fine so long as the information is there.
Also - on the TODO list - I don't know where to put this once it is finished.
I think that I have answered that in this comment https://github.com/mggg/GerryChain/pull/467/changes#r3687113591
There was a problem hiding this comment.
There are a lot of changes to the public signatures, and they might be easiest to organize this in the following way:
Renamed parameters
Parameters accepting functions now generally use the
_fnsuffix:
proposal→proposal_fn
MarkovChainSingleMetricOptimizerGingleator
There was a problem hiding this comment.
I started down the path of documenting every place where a parameter name was changed to end in "_fn" and then realized that I was violating the "terse" change-log goal.
This is where I stopped:
* proposal → proposal_fn
* MarkovChain
* SingleMetricOptimizer
* Gingleator
* ??? → acceptance_fn
* MarkovChain
* SingleMetricOptimizer.short_burts()
* ???
* ??? → value_fn
* Bounds
* ??? → score_fn
* Gingleator
* SingleMetricOptimizer
* ??? → optimization_metric_fn
* SingleMetricOptimizer
* ??? → beta_fn
* SingleMetricOptimizer.simulated_annealing()
* ??? → container_fn
* assignmewnt.level_sets()---
I then shifted to just showing one example with the assumption that any code that used the old named parameter would be flagged, and users could easily just say: OK - try adding an "_fn" to the name...
However, if you really want the entire list, I can do that...
Renamed parameters that accept functions
-
Parameters accepting functions now generally have names that use the _fn suffix:
This is only an issue for function calls using named parameters.
An example of this is the renaming of "proposal" to "proposal_fn" in the constructor for a MarkovChain object:
Old:
my_chain = MarkovChain( proposal = my_proposal, ... )New:
my_chain = MarkovChain( proposal_fn = my_proposal, ... )
There was a problem hiding this comment.
With the deprecation shims in place, and the minimality of the change (post-fixing _fn), this is probably sufficient. I'll handle the emails of anyone who is confused
| #### ? | ||
|
|
||
| # DELETE EVERYTHING BELOW HERE | ||
| After checking with Peter |
There was a problem hiding this comment.
Good to go after addressing above comments.
There was a problem hiding this comment.
Can we change this file name to "CHANGELOG.md". When that is finished, we can add it to the documentation by
- Creating a file called "docs/topics/CONTRIBUTING.md" and ad: this to it:
```{include} ../../CHANGELOG.md
```
- In docs/index.md, we should update the format to look like
```{toctree}
:hidden:
:caption: Topics
:maxdepth: 1
topics/v1p0p0_migration_guide
topics/reproducibility
topics/tools
```
```{toctree}
:hidden:
:caption: Help and Project
:maxdepth: 1
topics/changelog
topics/contributing
topics/reporting
```
There was a problem hiding this comment.
I am inclined to let you do this, because I am not confident that I know how to configure the docs correctly.
On the one hand, how hard could it be, but on the other hand, it looks to be trivial for someone who knows how to do it, so why take the chance of screwing up?
So, I am planning to leave the current file as-is, and let you rename it in git and put it where you want and then update the docs tables of contents, etc.
Also TBD is to add the actual links in the change-log to other documentation. I have flagged each place where a link is needed with my standard: frm: TODO: prefix.
In short, I am assuming that it would take you longer to explain to me what I need to do than it would take you to just do it. If that is not correct, then just tell me to not be a scaredy-cat and to just do it...
There was a problem hiding this comment.
That's no problem; I'm happy to do all of this.
|
I will attack this tomorrow (Friday)
…On Thu, Jul 30, 2026 at 8:13 PM Peter ***@***.***> wrote:
***@***.**** requested changes on this pull request.
This is very close to ready. Responses to a couple of your questions:
... who is the audience? Is it the same audience as the migration guide or
is it for gerrychain developers? That is, users vs contributors?
The migration guide is for normal users, and the CHANGELOG will be
targeting "super" users.
What level of detail do you want? For instance do you want changes in
parameters and parameter names or is that too detailed?
This CHANGELOG should be thorough, but terse. Users should be able to
ctrl+f to find information, but the prose should be limited to only what is
strictly necessary to understand the change. So, sentence fragments are
fine so long as the information is there.
Also - on the TODO list - I don't know where to put this once it is
finished.
I think that I have answered that in this comment
https://github.com/mggg/GerryChain/pull/467/changes#r3687113591
------------------------------
In gerrychain/graph/__init__.py
<#467 (comment)>:
> a GerryChain Graph object using from_networkx().
+For instance:
+
+ import networkx
+ from gerrychain import Graph
+
+ # Create a NetworkX graph
+ nx_graph = networkx.Graph()
+ nx_graph.add_edges_from(...)
+
+ # Create a GerryChain graph from the NetworkX graph
+ my gerrychain_graph = Graph.from_networkx(nx_graph)
⬇️ Suggested change
- my gerrychain_graph = Graph.from_networkx(nx_graph)
+ my_gerrychain_graph = Graph.from_networkx(nx_graph)
------------------------------
In gerrychain/graph/__init__.py
<#467 (comment)>:
> a GerryChain Graph object using from_networkx().
+For instance:
+
+ import networkx
+ from gerrychain import Graph
+
+ # Create a NetworkX graph
+ nx_graph = networkx.Graph()
+ nx_graph.add_edges_from(...)
+
+ # Create a GerryChain graph from the NetworkX graph
+ my gerrychain_graph = Graph.from_networkx(nx_graph)
+
Internally, a Graph object contains and embedded graph
⬇️ Suggested change
-Internally, a Graph object contains and embedded graph
+Internally, a Graph object contains an embedded graph
------------------------------
On v1.0.0_changelog.md
<#467 (comment)>:
There are a lot of changes to the public signatures, and they might be
easiest to organize this in the following way:
Renamed parameters
Parameters accepting functions now generally use the _fn suffix:
- proposal → proposal_fn
- MarkovChain
- SingleMetricOptimizer
- Gingleator
------------------------------
In v1.0.0_changelog.md
<#467 (comment)>:
> +#### Changes to function names:
+
+* In module constraints:
+
+ * L1_polsby_popper() renamed to be: L_1_polsby_popper()
+ * L1_reciprocal_polsby_popper() renamed to be: L_1_reciprocal_polsby_popper()
+
+* In module grid:
+
+ * create_grid_graph() renamed to be: create_grid_nx_graph()
+
+#### Changes to names for function parameters
+
+* GerryChain has adopted the convention that the names of parameters that are themselves function will end in "_fn".
+
+### Removed
I think this is all we really need here
Removed
- Removed the pre-1.0 NetworkX-derived Graph interface. In particular,
Graph is no longer a
networkx.Graph. See the migration guide for the replacement graph
operations.
- (Rarely used) Removed the old instantiable and callable ReCom
interface. Use the proposal
builders on the ReCom namespace.
------------------------------
In v1.0.0_changelog.md
<#467 (comment)>:
> @@ -0,0 +1,344 @@
+## [v1.0.0] - August 2026
+
+### Added
Missing gerrymandria()
------------------------------
In v1.0.0_changelog.md
<#467 (comment)>:
> +
+ * L1_polsby_popper() renamed to be: L_1_polsby_popper()
+ * L1_reciprocal_polsby_popper() renamed to be: L_1_reciprocal_polsby_popper()
+
+* In module grid:
+
+ * create_grid_graph() renamed to be: create_grid_nx_graph()
+
+#### Changes to names for function parameters
+
+* GerryChain has adopted the convention that the names of parameters that are themselves function will end in "_fn".
+
+### Removed
+#### ?
+#### ?
+
We should add a "Deprecated" section that metion:
- Pre-1.0 proposal and acceptance callbacks that omit rng remain
temporarily supported with warnings.
- The legacy constructor and method parameter names for MarkovChain,
Gingleator, SingleMetricOptimizer, etc. remain temporarily supported with
warnings.
------------------------------
In v1.0.0_changelog.md
<#467 (comment)>:
> +* In module constraints:
+
+ * L1_polsby_popper() renamed to be: L_1_polsby_popper()
+ * L1_reciprocal_polsby_popper() renamed to be: L_1_reciprocal_polsby_popper()
I actually changed these back in #468
<#468>
------------------------------
In v1.0.0_changelog.md
<#467 (comment)>:
> + * L1_reciprocal_polsby_popper() renamed to be: L_1_reciprocal_polsby_popper()
+
+* In module grid:
+
+ * create_grid_graph() renamed to be: create_grid_nx_graph()
+
+#### Changes to names for function parameters
+
+* GerryChain has adopted the convention that the names of parameters that are themselves function will end in "_fn".
+
+### Removed
+#### ?
+#### ?
+
+# DELETE EVERYTHING BELOW HERE
+After checking with Peter
Good to go after addressing above comments.
------------------------------
On v1.0.0_changelog.md
<#467 (comment)>:
Can we change this file name to "CHANGELOG.md". When that is finished, we
can add it to the documentation by
1. Creating a file called "docs/topics/CONTRIBUTING.md" and ad: this
to it:
```{include} ../../CHANGELOG.md
```
2. In docs/index.md, we should update the format to look like
```{toctree}
:hidden:
:caption: Topics
:maxdepth: 1
topics/v1p0p0_migration_guide
topics/reproducibility
topics/tools
```
```{toctree}
:hidden:
:caption: Help and Project
:maxdepth: 1
topics/changelog
topics/contributing
topics/reporting
```
—
Reply to this email directly, view it on GitHub
<#467?email_source=notifications&email_token=AAVB2BGKP533BFOJ5EJSFFL5HPQBTA5CNFSNUABKM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UKJSXM2LFO4XTIOBSGI4DKMBQHAY2M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KYZTPN52GK4S7MNWGSY3L#pullrequestreview-4822850081>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAVB2BGAHDDFRN43YC6QBPT5HPQBTAVCNFSNUABFKJSXA33TNF2G64TZHMYTGNRWHAZTMOJWHNEXG43VMU5TKMBRGI3TQOJYHAZ2C5QC>
.
Triage notifications, keep track of coding agent tasks and review pull
requests on the go with GitHub Mobile for iOS
<https://github.com/notifications/mobile/ios/AAVB2BBSIEHAOLFBC2PY4V35HPQBTA5CNFSNUABKM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UKJSXM2LFO4XTIOBSGI4DKMBQHAY2M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KUZTPN52GK4S7NFXXG>
and Android
<https://github.com/notifications/mobile/android/AAVB2BB2GIVPLTS6KIYKSPD5HPQBTA5CNFSNUABKM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UKJSXM2LFO4XTIOBSGI4DKMBQHAY2M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2K4ZTPN52GK4S7MFXGI4TPNFSA>.
Download it today!
You are receiving this because you authored the thread.Message ID:
***@***.***>
|
Co-authored-by: Peter <27579114+peterrrock2@users.noreply.github.com>
Merge remote-tracking branch 'refs/remotes/origin/frm_rustworkx_post_alpha' into frm_rustworkx_post_alpha
chief-dweeb
left a comment
chief-dweeb
left a comment
There was a problem hiding this comment.
Tag you're it (again)...
As stated in my comments, I have done almost everything you asked for.
I did not list every parameter name change that added "_fn" to the end of a function parameter.
I did not add the links from this documentation to other documentation. I am hoping it will be trivial for you to do that, but if not, send it back my way and I will figure it out.
There was a problem hiding this comment.
I am inclined to let you do this, because I am not confident that I know how to configure the docs correctly.
On the one hand, how hard could it be, but on the other hand, it looks to be trivial for someone who knows how to do it, so why take the chance of screwing up?
So, I am planning to leave the current file as-is, and let you rename it in git and put it where you want and then update the docs tables of contents, etc.
Also TBD is to add the actual links in the change-log to other documentation. I have flagged each place where a link is needed with my standard: frm: TODO: prefix.
In short, I am assuming that it would take you longer to explain to me what I need to do than it would take you to just do it. If that is not correct, then just tell me to not be a scaredy-cat and to just do it...
There was a problem hiding this comment.
I started down the path of documenting every place where a parameter name was changed to end in "_fn" and then realized that I was violating the "terse" change-log goal.
This is where I stopped:
* proposal → proposal_fn
* MarkovChain
* SingleMetricOptimizer
* Gingleator
* ??? → acceptance_fn
* MarkovChain
* SingleMetricOptimizer.short_burts()
* ???
* ??? → value_fn
* Bounds
* ??? → score_fn
* Gingleator
* SingleMetricOptimizer
* ??? → optimization_metric_fn
* SingleMetricOptimizer
* ??? → beta_fn
* SingleMetricOptimizer.simulated_annealing()
* ??? → container_fn
* assignmewnt.level_sets()---
I then shifted to just showing one example with the assumption that any code that used the old named parameter would be flagged, and users could easily just say: OK - try adding an "_fn" to the name...
However, if you really want the entire list, I can do that...
Renamed parameters that accept functions
-
Parameters accepting functions now generally have names that use the _fn suffix:
This is only an issue for function calls using named parameters.
An example of this is the renaming of "proposal" to "proposal_fn" in the constructor for a MarkovChain object:
Old:
my_chain = MarkovChain( proposal = my_proposal, ... )New:
my_chain = MarkovChain( proposal_fn = my_proposal, ... )
There was a problem hiding this comment.
That's no problem; I'm happy to do all of this.
There was a problem hiding this comment.
With the deprecation shims in place, and the minimality of the change (post-fixing _fn), this is probably sufficient. I'll handle the emails of anyone who is confused
2 participants
Summary
Created a change-log for the RustworkX migration vis-a-vis the currently released GerryChain.
Changes
Added a new file, v1.0.0_changelog.md
Testing
N/A - just documentation
Reviewer Notes
Need feedback on format and on the "Notes" that I have added.
Also need to know where to put this content once it has been approved.