Migrating to towncrier for changelog

[devanshshukla99]

This Pull Request migrates the changelog to towncrier, fixes #554.

As described in the original issue, this PR adds relevant instructions on how to use towncrier as well as a gh-action workflow to check for the changelog entry.

Migrating to towncrier is pretty easy, instead of adding details to the CHANGELOG.rst, add a file named <pr number>.<type>.rst to docs/changes/ directory.

Right now, it supports following types (following suit of astropy and pytest):

• breaking: A change which is not backwards compatible and requires users to change code.
• feature: New user facing features and any new behavior.
• bugfix: Fixes a reported bug.
• doc: Documentation improvement, like rewording an entire session or adding missing docs.
• deprecation: Feature deprecation.
• removal: Feature removal.
• trivial: Fixes a small typo or internal change that might be noteworthy.

With other relevant details available at docs/changes/README.rst

The gh-action workflow check-changelog.yml will only check if there is a file named <pr number>.*.rst and can be skipped by using no-changelog-entry-needed label on the PR.

Changelog generated using towncrier:

v1.1.2.dev52+g951a854 (2023-03-07)
----------------------------------

Internal Changes
^^^^^^^^^^^^^^^^

- Using `towncrier <https://github.com/hawkowl/towncrier>`__ to generate the changelogs. (`#697 <https://github.com/StingraySoftware/stingray/pull/697>`__)


v1.1.1 (2022-10-10)
-------------------
Bug fixes
^^^^^^^^^
- Fixed ``white_noise_offset`` in ``compute_rms`` to 2.0, as it should be
- Fixed a bug that produced a crash when calculating the rms in spectra corrected through the FAD technique
- Fixed a bug that eliminated the imaginary part from cross spectra corrected with the FAD
- Fixed a bug that considered contiguous GTIs as non-continuous (due to very small differences between stop and start of the next GTI) by allowing a small tolerance

`Full list of changes`__

__ https://github.com/StingraySoftware/stingray/compare/v1.1...v1.1.1


v1.1 (2022-10-02)
-----------------
Bug fixes
^^^^^^^^^
- IMPORTANT: Fixed sign of time lags, which were calculated using the interest band as the reference.
- Fixed an issue when the fractional exposure in FITS light curves is slightly >1 (as sometimes happens in NICER data)

New
^^^
- Implemented the ``bexvar`` variability estimation method for light curves.

Improvements
^^^^^^^^^^^^
- A less confusing default value of segment_size in Z searches

`Full list of changes`__

__ https://github.com/StingraySoftware/stingray/compare/v1.0...v1.1

v1.0 (2022-03-29)
---------------------
TL,DR: these things will break your code with v1.0:

- Python version < 3.8
- The ``gtis`` keyword in `pulse/pulsar.py` (it is now ``gti``, without the 's')

New
^^^
- Dropped support to Python < 3.8
- Multi-taper periodogram, including a Lomb-Scargle implementation for non-uniformly sampled data
- Create count-rate spectrum when calculating spectral-timing products
- Make modlation upper limit in ``(Averaged)Powerspectrum`` work with any normalization (internally converts to Leahy for the calculation)
- Implement Gardner-Done normalization (1 for perfect correlation, -1 for perfect anticorrelation) for ``Auto/Crosscorrelation``
- New infrastructure for converting ``EventList`` and ``LightCurve`` objects into Astropy ``TimeSeries``
- New infrastructure for converting most Stingray classes into Astropy ``Table`` objects, Xarray and Pandas data frames.
- Save and load of most Stingray classes to/from many different file formats (``pickle``, ``ECSV``, ``HDF5``, ``FITS``, and all formats compatible with Astropy Table)
- Accept input ``EventList`` in ``DynamicalPowerSpectrum``
- New ``stingray.fourier`` module containing the basic timing products, usable on ``numpy`` arrays, and centralizes fft import
- New methods in ``Crossspectrum`` and ``Powerspectrum`` to load data from specific inputs: ``from_events``, ``from_lightcurve``, ``from_time_array``, ``from_lc_list`` (``from_time_array`` was also tested using memory-mapped event lists as inputs: useful in very large datasets)
- New and improved spectral timing methods: ``ComplexCovarianceSpectrum``, ``CovarianceSpectrum``, ``LagSpectrum``, ``RmsSpectrum``
- Some deprecated features are now removed
- ``PSDLogLikelihood`` now also works with a log-rebinned PDS

Improvements
^^^^^^^^^^^^
- Performance on large data sets is VASTLY improved
- Lots of performance improvements in the ``AveragedCrossspectrum`` and ``AveragedPowerspectrum`` classes
- Standardized use of new fast psd/cs algorithm, with ``legacy`` still available as an alternative option to specify
- Reading calibrated photon energy from event files by default
- In ``pulse/pulsar.py``, methods use the keyword ``gti`` instead of ``gtis`` (for consistency with the rest of Stingray)
- Moved ``CovarianceSpectrum` to ``VarEnergySpectrum`` and reuse part of the machinery
- Improved error bars on cross-spectral and spectral timing methods
- Measure absolute rms in ``RmsEnergySpectrum``
- Friendlier ``pyfftw`` warnings
- Streamline PDS/CrossSp production, adding ``from_events``, ``from_lc``, ``from_lc_iterable``, and ``from_time_array`` (to input a numpy array) methods
- PDS/CrossSp initially store the unnormalized power, and convert it on the fly when requested, to any normalization

Bug fixes
^^^^^^^^^
- Fixed error bars and ``err_dist`` for sliced (iterated) light curves and power spectra
- Fixed a bug in how the start time when applying GTIs (now using the minimum value of the GTI array, instead of half a time bin below the minimum value)
- Fixed a bug in which all simulator errors were incorrectly non-zero
- Fixed coherence uncertainty
- Documented a Windows-specific issue when large count rate light curves are defined as integer arrays (Windows users should use ``float`` or specify ``int-64``)
- If the variance of the lightcurve is zero, the code will fail to implement Leahy normalization
- The value of the ``PLEPHEM`` header keyword is forced to be a string, in the rare cases that it's a number
- and more!

`Full list of changes`__

__ https://github.com/StingraySoftware/stingray/compare/v0.3...v1.0

v1.0beta was released on 2022-02-25.

v0.3 (2021-05-31)
-----------------

- Lots of performance improvements
- Faster simulations
- Averaged Power spectra and Cross spectra now handle Gaussian light curves correctly
- Fixes in rebin functions
- New statistical functions for signal detection in power spectra and pulsar search periodograms
- Much improved FTOOL-compatible mission support
- New implementation of the FFTFIT method to calculate pulsar times of arrival
- H-test for pulsar searches
- Z^2_n search adapted to binned and normally distribute pulse profiles
- Large data processing (e.g. from NICER) allowed
- Rebinning function now accepts unevenly sampled data
- New saving and loading from/to Astropy Tables and Timeseries
- Improved I/O to ascii, hdf5 and other formats
- Rehaul of documentation

`Full list of changes`__

__ https://github.com/StingraySoftware/stingray/compare/v0.2...v0.3

v0.2 (2020-06-17)
-----------------

- Added Citation info
- Fixed various normalization bugs in Powerspectrum
- Speedup of lightcurve creation and handling
- Made code compatible with Python 3.6, and dropped support to Python 2.7
- Test speedups
- Dead time models and Fourier Amplitude Difference correction
- Roundtrip of LightCurve to lightkurve objects
- Fourier-domain accelerated search for pulsars
- Adapt package to APE-17
- Periodograms now also accept event lists (instead of just light curves)
- Allow transparent MJDREF change in event lists and light curves

`Full list of changes`__

__ https://github.com/StingraySoftware/stingray/compare/v0.1.3...v0.2

v0.1.3 (2019-06-11)
-------------------

- Bug fixes

v0.1.2
------

- Bug fixes

v0.1.1
------

- Bug fixes

v0.1 (2019-05-29)
-----------------

- Initial release.

[codecov]

Codecov Report

Merging #697 (3f7307c) into main (dd74a00) will increase coverage by 0.01%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##             main     #697      +/-   ##
==========================================
+ Coverage   97.20%   97.21%   +0.01%     
==========================================
  Files          42       42              
  Lines        7793     7797       +4     
==========================================
+ Hits         7575     7580       +5     
+ Misses        218      217       -1     

Impacted Files	Coverage Δ
stingray/io.py	98.78% <0.00%> (ø)
stingray/gti.py	99.27% <0.00%> (ø)
stingray/base.py	96.98% <0.00%> (ø)
stingray/stats.py	99.47% <0.00%> (ø)
stingray/utils.py	99.01% <0.00%> (ø)
stingray/bexvar.py	98.88% <0.00%> (ø)
stingray/events.py	100.00% <0.00%> (ø)
stingray/filters.py	99.07% <0.00%> (ø)
stingray/fourier.py	99.74% <0.00%> (ø)
stingray/__init__.py	100.00% <0.00%> (ø)
... and 31 more

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

[matteobachetti]

Thanks @devanshshukla99, this is very useful!

An important thing to pay attention to: we should make sure that the format of the changelog is consistent with the old changelog, because the documentation build should have consistent titles. At the moment, the modifications of the development version have a different formatting, in particular a different title level.

[devanshshukla99]

Thanks @devanshshukla99, this is very useful!

An important thing to pay attention to: we should make sure that the format of the changelog is consistent with the old changelog, because the documentation build should have consistent titles. At the moment, the modifications of the development version have a different formatting, in particular a different title level.

Thanks for the review!
The title levels are now consistent with the old changelogs.

[dhuppenkothen]

This looks great! Thank you for implementing this! One thing I’m curious about: is the new changelog going to be displayed on our documentation? And if not, is there a way to make that happen? Doesn’t have to be in this PR. Just flagging it in case we should open another issue to do that.

[matteobachetti]

@dhuppenkothen I think it does, here: https://docs.stingray.science/history.html#changelog. The source file has an include instruction for CHANGELOG.rst. We should just make sure that the CHANGELOG generation is done before the docs build (Tagging @jdswinbank too here)

[matteobachetti]

@devanshshukla99 we are almost there. The docs build is failing because the rst file of the towncrier snippet is not included in any toctree. Of course, it does not need to be included in any toctree, but there should be a way to avoid this conflict, for example excluding files with a given pattern in the name from sphinx.

[matteobachetti]

Thanks @devanshshukla99 !