diff --git a/docs/CHANGES.md b/docs/CHANGES.md
index 699aa7dcf5c..d97ed7c644a 100644
--- a/docs/CHANGES.md
+++ b/docs/CHANGES.md
@@ -6,6 +6,57 @@ nav_order: 4
 
 # Changelog
 
+## 2024.5.31
+
+### 🐛 Bug Fixes
+
+* Make `Beautifulsoup` optional by @ab5424 in https://github.com/materialsproject/pymatgen/pull/3774
+* Fix overlayed subplots in `BSPlotterProjected.get_projected_plots_dots()` by @janosh in https://github.com/materialsproject/pymatgen/pull/3798
+* Fix `_get_dipole_info` for DDEC6 `ChargemolAnalysis` and add test case by @JonathanSchmidt1 in https://github.com/materialsproject/pymatgen/pull/3801
+* `Cp2kOutput.parse_initial_structure()` use regex for line matching to allow arbitrary white space between Atom/Kind/Element/... by @janosh in https://github.com/materialsproject/pymatgen/pull/3810
+* Fix the minor document error in `POTCAR Setup`. by @hongyi-zhao in https://github.com/materialsproject/pymatgen/pull/3834
+* Use `isclose` over `==` for overlap position check in `SlabGenerator.get_slabs` by @DanielYang59 in https://github.com/materialsproject/pymatgen/pull/3825
+* [Deprecation] Replace `Element` property `is_rare_earth_metal` with `is_rare_earth` to include Y and Sc  by @DanielYang59 in https://github.com/materialsproject/pymatgen/pull/3817
+
+### 🛠 Enhancements
+
+* Add `is_radioactive` property to Element class by @AntObi in https://github.com/materialsproject/pymatgen/pull/3804
+* Add a `from_ase_atoms()` method to `Structure` by @Andrew-S-Rosen in https://github.com/materialsproject/pymatgen/pull/3812
+* Adapt to the latest version of PWmat output file by @lhycms in https://github.com/materialsproject/pymatgen/pull/3823
+* Update VASP sets to transition atomate2 to use pymatgen input sets exclusively by @esoteric-ephemera in https://github.com/materialsproject/pymatgen/pull/3835
+
+### 📖 Documentation
+
+* Imperative `get_...` method and `@property` doc strings by @janosh in https://github.com/materialsproject/pymatgen/pull/3802
+* Doc string standardization by @janosh in https://github.com/materialsproject/pymatgen/pull/3805
+
+### 🧹 House-Keeping
+
+* Add types for `core.(molecular_orbitals|operations|sites|spectrum|tensor|xcfunc)` by @DanielYang59 in https://github.com/materialsproject/pymatgen/pull/3829
+* Move test structures out of `util` directory by @DanielYang59 in https://github.com/materialsproject/pymatgen/pull/3831
+
+### 🧪 Tests
+
+* Improve type annotations for `core.(trajectory/units)` by @DanielYang59 in https://github.com/materialsproject/pymatgen/pull/3832
+
+### 🏷️ Type Hints
+
+* More type annotations by @janosh in https://github.com/materialsproject/pymatgen/pull/3800
+* Add types for `core.periodic_table/bonds/composition/ion/lattice/libxcfunc`, new type `MillerIndex` and fix Lattice hash by @DanielYang59 in https://github.com/materialsproject/pymatgen/pull/3814
+* Guard `TYPE_CHECKING` only imports by @DanielYang59 in https://github.com/materialsproject/pymatgen/pull/3827
+* Improve type annotations and comments for `io.cif` by @DanielYang59 in https://github.com/materialsproject/pymatgen/pull/3820
+* Improve type annotations for `core.structure` by @DanielYang59 in https://github.com/materialsproject/pymatgen/pull/3837
+
+### 🤷‍♂️ Other Changes
+
+* mixing scheme: change default for verbose by @tschaume in https://github.com/materialsproject/pymatgen/pull/3806
+* `ruff` 0.4.3 auto-fixes by @janosh in https://github.com/materialsproject/pymatgen/pull/3808
+* Re-enable some useful `ruff` rules by @DanielYang59 in https://github.com/materialsproject/pymatgen/pull/3813
+* `pandas.read_csv`: replace deprecated `delim_whitespace=True` with `sep="\s+"` by @ab5424 in https://github.com/materialsproject/pymatgen/pull/3846
+* Improve unphysical (greater than 1) occupancy handling in `CifParser` and add missing site label `if not check_occu` by @DanielYang59 in https://github.com/materialsproject/pymatgen/pull/3819
+
+**Full Changelog**: https://github.com/materialsproject/pymatgen/compare/v2024.5.1...v2024.5.31
+
 ## v2024.5.1
 
 ### 🐛 Bug Fixes
diff --git a/setup.py b/setup.py
index ded1a838809..48df3317ded 100644
--- a/setup.py
+++ b/setup.py
@@ -25,7 +25,7 @@
 setup(
     name="pymatgen",
     packages=find_namespace_packages(include=["pymatgen.*", "pymatgen.**.*"]),
-    version="2024.5.1",
+    version="2024.5.31",
     python_requires=">=3.9",
     install_requires=[
         "matplotlib>=1.5",