diff --git a/.gitignore b/.gitignore index 4ffab5fb4..779ff562a 100644 --- a/.gitignore +++ b/.gitignore @@ -16,6 +16,8 @@ docs/_build/ docs/src/generated/ docs/src/sg_execution_times.rst tools/documentation_developer/CONTRIBUTING.rst +tools/documentation_developer/CONTRIBUTORS.rst +docs/src/whats_news/CHANGELOG.rst # file generated by hatch src/hidimstat/_version.py diff --git a/CHANGELOG.rst b/CHANGELOG.rst new file mode 100644 index 000000000..9e1e23b7e --- /dev/null +++ b/CHANGELOG.rst @@ -0,0 +1,25 @@ +================================= +Version 1.1 (under devellopement) +================================= + +HIGHLIGHTS +---------- + + +New features +------------ + + +Changes +------- + + +Bug fixes +--------- + + +Maintenance +----------- + +Contributors +------------ diff --git a/CONTRIBUTOR.rst b/CONTRIBUTOR.rst new file mode 100644 index 000000000..f59322fe5 --- /dev/null +++ b/CONTRIBUTOR.rst @@ -0,0 +1,32 @@ +Version 0.1.0 (see https://github.com/ja-che/hidimstat) +------------------------------------------------------- +https://github.com/ja-che +https://github.com/tbng +https://github.com/agramfort +https://github.com/GuillaumeFavelier + +Version 0.1.1 (see https://github.com/Parietal-INRIA/hidimstat) +--------------------------------------------------------------- +https://github.com/tbng +https://github.com/bthirion +https://github.com/achamma723 + +Version 0.2.0 +------------- +https://github.com/tbng +https://github.com/bthirion +https://github.com/achamma723 + +Version 1.0.0 +------------- +https://github.com/bthirion +https://github.com/AngelReyero +https://github.com/jpaillard +https://github.com/lionelkusch +https://github.com/tbng +https://github.com/Remi-Gau +https://github.com/jeromedockes +https://github.com/glemaitre +https://github.com/antoinebaker +https://github.com/man-shu +https://github.com/alexblnn \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile index 630adc24c..74a83c5c4 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -62,6 +62,9 @@ clean: rm -rfv $(BUILDDIR)/* rm -rfv $(SOURCEDIR)/generated/* rm -rfv $(SOURCEDIR)/sg_execution_times.rst + rm -rfv $(SOURCEDIR)/whats_news/CHANGELOG.rst + rm -rfv $(SOURCEDIR)/dev/CONTRIBUTING.rst + rm -rfv $(SOURCEDIR)/dev/CONTRIBUTORS.rst html-noplot: $(SPHINXBUILD) -D plot_gallery=0 -b html $(ALLSPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/html diff --git a/docs/src/index.rst b/docs/src/index.rst index 315331aa6..64f97fb58 100644 --- a/docs/src/index.rst +++ b/docs/src/index.rst @@ -135,4 +135,5 @@ References user_guide generated/gallery/examples/index glossary_and_notations + whats_news/whats_news dev/index diff --git a/docs/src/whats_news/latest.rst b/docs/src/whats_news/latest.rst new file mode 120000 index 000000000..e03087ef6 --- /dev/null +++ b/docs/src/whats_news/latest.rst @@ -0,0 +1 @@ +v1.0.0.rst \ No newline at end of file diff --git a/docs/src/whats_news/v1.0.0.rst b/docs/src/whats_news/v1.0.0.rst new file mode 100644 index 000000000..5e0ccdd87 --- /dev/null +++ b/docs/src/whats_news/v1.0.0.rst @@ -0,0 +1,3 @@ +============== +Version 1.0.0 +============== diff --git a/docs/src/whats_news/whats_news.rst b/docs/src/whats_news/whats_news.rst new file mode 100644 index 000000000..fd782e9b8 --- /dev/null +++ b/docs/src/whats_news/whats_news.rst @@ -0,0 +1,30 @@ +.. _whats_new: + +========== +What's new +========== + +==================== +Latest modification +==================== + +.. _latest: +.. include:: latest.rst + +.. _changelog: +.. include:: CHANGELOG.rst + + +======================= +History of modification +======================= + +.. _v1.0.0: +.. include:: v1.0.0.rst + +.. toctree:: + :hidden: + :maxdepth: 1 + + v1.0.0 + latest \ No newline at end of file diff --git a/docs/tools/_templates/CHANGELOG.rst b/docs/tools/_templates/CHANGELOG.rst new file mode 100644 index 000000000..4646eb0d8 --- /dev/null +++ b/docs/tools/_templates/CHANGELOG.rst @@ -0,0 +1,25 @@ +================================= +Version X.Y.Z (under devellopement) +================================= + +HIGHLIGHTS +---------- + + +New features +------------ + + +Changes +------- + + +Bug fixes +--------- + + +Maintenance +----------- + +Contributors +------------ \ No newline at end of file diff --git a/docs/tools/conf.py b/docs/tools/conf.py index 038471ebc..1957fa27a 100644 --- a/docs/tools/conf.py +++ b/docs/tools/conf.py @@ -28,6 +28,8 @@ # We avoid duplicating the information, but we do not use symlinks to be # able to build the docs on Windows shutil.copyfile("../../CONTRIBUTING.rst", "../src/dev/CONTRIBUTING.rst") +shutil.copyfile("../../CONTRIBUTOR.rst", "../src/dev/CONTRIBUTORS.rst") +shutil.copyfile("../../CHANGELOG.rst", "../src/whats_news/CHANGELOG.rst") # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration @@ -95,6 +97,12 @@ "header_links_before_dropdown": 4, "pygments_light_style": "sas", "pygments_dark_style": "monokai", + "switcher": { + "json_url": ( + "https://raw.githubusercontent.com/mind_inria/hidimstat/main/doc_conf/version.json" + ), + "version_match": release, + }, } html_title = "HiDimStat" diff --git a/docs/tools/version.json b/docs/tools/version.json new file mode 100644 index 000000000..4014f6fdd --- /dev/null +++ b/docs/tools/version.json @@ -0,0 +1,33 @@ +[ + { + "name": "1.1.dev0 (dev)", + "version": "1.1.dev0", + "url": "https://hidimstat.github.io/dev/" + }, + { + "name": "1.0 (stable)", + "version": "1.0", + "url": "https://hidimstat.github.io/stable/", + "preferred": true + }, + { + "name": "1.0 (stable)", + "version": "1.0", + "url": "https://hidimstat.github.io/1.0/" + }, + { + "name": "0.2.0", + "version": "0.2.0", + "url": "https://hidimstat.github.io/0.2/" + }, + { + "name": "0.1.1", + "version": "0.1.1", + "url": "https://hidimstat.github.io/0.1.1/" + }, + { + "name": "0.1.0", + "version": "0.1.0", + "url": "https://hidimstat.github.io/0.1.0/" + } +] \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 635d31f64..525319d6b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,32 +1,34 @@ [build-system] -requires = ["hatchling", "hatch-vcs"] -build-backend = "hatchling.build" +requires = [ + "setuptools >= 64, < 100", # builder for python packages + "setuptools_scm[toml] >= 8, < 50" # plugging for getting the version from github + ] +build-backend = "setuptools.build_meta" [project] name = "HiDimStat" -# Version from setuptools_scm -dynamic = ["version"] -dependencies = [ - "joblib >= 1.2.0, < 2", - "numpy >= 1.25, < 3", - "pandas >= 2.2, < 3", - "scikit-learn >= 1.5, < 1.9", - "scipy >= 1.9.2, < 2", - "tqdm >= 4.1.0, < 5", -] -requires-python = ">=3.10, < 4" -authors = [{ name = "HiDimStat developers" }] +dynamic = ["version"] # dynamical version extracted from the git version +authors = [ # TODO see if we need more details + { name = "HiDimStat developers" } # possibility to add an email address + ] maintainers = [ { name = "Bertrand Thirion", email = "bertrand.thirion@inria.fr" }, ] +# Don't forget to have the coherence between the README and the description description = "High-dimensional statistical inference tools for Python" -readme = "README.rst" +keywords = ["statistic", "high dimension", "importance variable"] +readme = "README.md" +license = { file = "LICENSE" } classifiers = [ "Intended Audience :: Science/Research", "Intended Audience :: Developers", + "License :: OSI Approved :: BSD License", "Operating System :: Microsoft :: Windows", "Operating System :: Unix", "Operating System :: MacOS", + "Operating System :: OS Independent", + "Programming Language :: Python :: 3:: Only", + "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", @@ -34,7 +36,15 @@ classifiers = [ "Topic :: Software Development", "Topic :: Scientific/Engineering", ] -license = { file = "LICENSE" } +requires-python = ">=3.10, < 4" +dependencies = [ + "joblib >= 1.2.0, < 2", + "numpy >= 1.25, < 3", + "pandas >= 2.2, < 3", + "scikit-learn >= 1.5, < 1.9", + "scipy >= 1.9.2, < 2", + "tqdm >= 4.1.0, < 5", +] [project.optional-dependencies] # Requirements necessary for building the documentation @@ -74,30 +84,28 @@ test = [ ] [project.urls] -Development = "https://github.com/nilearn/nilearn" -Homepage = "https://mind-inria.github.io/hidimstat" Repository = "https://github.com/mind-inria/hidimstat" +Documentation = "https://github.com/hidimstat/hidimstat.github.io" +Teams = "https://team.inria.fr/mind/" +Issues = "https://github.com/mind-inria/hidimstat/issues" +Discussion = "https://github.com/mind-inria/hidimstat/discussions" # TODO see if we keep it or not +# Configuration of the builder +[tool.setuptools] +package-dir = {"" = "src"} # define the root of the packages as src + +# Configuration of static analysis [tool.codespell] builtin = "clear,rare,en-GB_to_en-US" skip = "./.git,*.bib,./docs/_build" [tool.isort] profile = "black" -skip = ["src/hidimstat/_version.py", "docs/_build"] - -[tool.hatch.build.hooks.vcs] -version-file = "src/hidimstat/_version.py" - -[tool.hatch.build.targets.wheel] -packages = ["src/hidimstat"] - -[tool.setuptools.packages.find] -where = ["src"] - +skip = ["src/hidimstat/_version.py", "docs/_build", "build/"] -[tool.hatch.version] -source = "vcs" +# file where the version is save +[tool.setuptools_scm] +version_file = "src/hidimstat/_version.py" # initialization based on the good practice of pytest # https://docs.pytest.org/en/stable/explanation/goodpractices.html diff --git a/tools/documentation_developer/index.rst b/tools/documentation_developer/index.rst index b035ceb55..9e31883e6 100644 --- a/tools/documentation_developer/index.rst +++ b/tools/documentation_developer/index.rst @@ -13,6 +13,12 @@ You need more information, look here: - :ref:`Continuous Integration` - :ref:`Building the documentation` +============ +CONTRIBUTORS +============ +.. _latest: +.. include:: CONTRIBUTORS.rst + .. toctree:: :hidden: @@ -20,3 +26,4 @@ You need more information, look here: how_to_contribute building_documentation CI_documentation + CONTRIBUTORS diff --git a/tools/release/How_to_release.md b/tools/release/How_to_release.md new file mode 100644 index 000000000..b97c7eb5d --- /dev/null +++ b/tools/release/How_to_release.md @@ -0,0 +1,155 @@ +--- +title: hidimstat-release + +--- +# How to create a release + +The simplest way to make a release can be find in this `tutorial ` + +The creation of the release is based on a builder. +We use `setuptools` has builder. This following links, we helps to configure it: +https://learn.scientific-python.org/development/guides/packaging-simple/ +https://setuptools.pypa.io/en/latest/userguide/quickstart.html +https://setuptools.pypa.io/en/latest/userguide/pyproject_config.html + +The version of the packages is defined dynamically based on the git tag using setuptools_scm. +For more details about it, look at this pages: +https://setuptools-scm.readthedocs.io/en/stable/usage/#builtin-mechanisms-for-obtaining-version-numbers + +The format of version tag is X.Y.Z: + - X represents a major revision (frequency: more than 1 year): + - Important modification of the API + - Refactoring of the major part of the code + - Y represents major release (frequency: 6 month to 1 year): + - Add new functionality (methods, functionalities, ...) + - Important modification of one function + - Z represents minor release (minimum: 1 days): + - Fix important bugs in a release + - Small modification of the example + - Adding new examples + +## Step for creating the Release: +This steps suppose that there a branch for each a major release (0.0.X). +The main branch is used for the ongoing work on the next major release. +For a major revision, a new branch should be create from scratch or from a commit of main. +For a modification of a previous release, the modification should be pushed on the branch associate to it. + # TODO check if it's necessary to have a script release/build_packages.py + +0. [Check if today is a good day for releasing](https://shouldideploy.today/) + +1\. Update the information related to the release: + - Update `CHANGELOG.rst` with the missing elements + - Update `CONTRIBUTORS.rst` with the missing contributors + +2\. Update the docstring of function based on CHANGELOG with ``deprecated``, ``versionchanged`` and ``versionadded`` directives. +Add ` .. versionadded:: x.y.z` in the docstring. +Additionally, make sure all deprecations that are supposed to be removed with this new version have been addressed. + +2\. Create create a tag and branches associate with the release. + + 1. git commit --allow-empty-message -m 'release X.Y.Z' + - **minor release of the ongoing release**: + 1. Create a branch `git checkout -b release-X.Y.(Z+1)` + 2. Add a tag on the last commit with the name of the release `git tag X.Y.(Z+1)` + - **major release**: + 1. A create a branch like `git checkout -b X.(Y+1).0` on the last commit of main + 2. (optional) `git rebase -i X.Y.Z` if you want to cherry pick some commits + 3. Add a tag to this branch with `git tag X.(Y+1).0` + - **major revision**: + 1. `git reset --hard (X+1).0.0` # Change main to major revion branch (with a force push) + 2. `git push -f mind-inria/main` # force to update main (disable the rule Prevent Branch deletion) + 3. `git checkout (X+1).0.0` # switch to the branch + 4. Add a tag on this version `(X+1).0.0` (the branch should be already create) `git tag (X+1).0.0` + +3\. build the wheel & test it + - `cd $(root of repository)` + - `rm -r release_file` # remove the previous build + - `mkdir release_file` + - `git pull` # update your repository + - `git checkout X.Y.Z` # checkout to the tag + - `python -m venv release_file/venv` # create virtual environment for testing the release + - `source release_file/venv/bin/activate` # activate this new venvironement + - `pip install build twines` # install packages for create a wheel and push it on pype + - `python -m build -o release_file/dist` (may need `pip install build`) # build the wheel + - `twine check release_file/_dist/*` (may need `pip install twine`) # check if the wheel is ready to be use + - `pip install release_file/dist/hidimstat.....whl` # install the wheel in a fresh virtualenv + - `pytest` # test the installation + +4\. Create a PR for creating the release: + 1. `git push --set-upstream origin X.Y.Z` + 2. Create a PR based on this new branch to the **right branch**. + +Merging this PR will update the documentation automatically + +5a. If you are on main => Update the changelog, contributor and version: + - Move the `CHANGELOG.rst` in the `doc_conf\whats_news\vX.Y.Z.rst` + `mv CHANGELOG.rst doc_conf\whats_news\vX.Y.Z.rst` + - Update symlink to latest version of the changelog: `ln -s vX.Y.Z.rst latest.rst` + - Replace `CHANGELOG.rst` with an empty template of `build_tools\template\CHANGELOG.rst` + `cp build_tools\template\CHANGELOG.rst CHANGELOG.rst` + - Change the version in this template and commit the modification + - Create a new entry in `doc_conf\whats_news\whats_news.rst` + - Update the file `CONTRIBUTORS.rst` in the documentation + `cp CONTRIBUTORS.rst doc_conf\whats_news\CONTRIBUTORS.rst` + - Add/Update the documentation with the new version. For doing it's require to update `doc_conf/version.json` which define all the version of the project.\ + The 2 first elements indicate the devellopement version and the last stable version. + - Update symlink to stable version in the github branches repo: https://github.com/hidimstat/hidimstat.github.io + + +5b. For minor release => Update the changelog, contributor: + - Modify the `build_tools\template\CHANGELOG.rst` with the modification + - Update `CONTRIBUTORS.rst` if it's necessary + - + +6\. Commit and push modification: + - Commit the modifications + - Push the modification + +7\. merge the PR on `0.4.X` (don't squash the commits) + - check if the tests are passed and the redering of the documentation, the examples, the changelog are good + - merge the PR **without squashing commit**: + no squash see warning in https://scikit-learn.org/dev/developers/maintainer.html#reference-steps \ + *NOTE*: in normal times only squash&merge is enabled because that's what we want for the main branch and we don't want to rebase or merge without squashing my mistake. there seems to be no way to configure this per branch ATM on github. so when we do a release we temporarily enable rebase. go to repository settings -> general -> pull requests, enable rebase, then merge the PR on 0.4.X (with the rebase option), then in the settings disable it again +- now we build the wheel we will upload to pypi locally `git fetch upstream` and `git checkout upstream/0.4.X` + +7\. Rebuild the wheel & retest it (see step [3]) + +8\. (Optional) upload to TestPyPi for testing (https://test.pypi.org/) + - `twine upload --repository testpypi release_file/dist/*` + - `python3 -m pip install --upgrade --force-reinstall ---index-url https://test.pypi.org/simple/ --no-deps --extra-index-url https://test.pypi.org/simple/hidismtat` + - `pytest` # test the installation + +9\. upload to pype + - `twine upload release_file/dist/*` + - (Optional) `python3 -m pip install --upgrade --force-reinstall --no-deps hidismtat==X.Y.Z` + - (Optional) `pytest` # test the installation + +10\. Update the tag + - Update the tag: `git tag -d X.Y.0` + - `git tag -s 'X.Y.Z'` # `-s` is for signing, optional + - `git push upstream X.Y.Z` # (disable the rule Prevent Branch deletion) + +11\. Create a release on github from a specific tag: + - See the following tutorial: https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#about-release-management + At this point, we need to upload the binaries to GitHub and link them to the tag. + To do so, go to the :nilearn-gh:`Hidimstat GitHub page ` under the "Releases" tab, and edit the ``x.y.z`` tag by providing a description, and upload the distributions we just created (you can just drag and drop the files). + +12\. Update the conda-forge recipe + - in `hidimstat-feedstock` https://github.com/conda-forge/hidimstat-feedstock + - create branch `release-X.Y.Z` + - update `recipe/meta.yml` + - that is the only file we ever edit manually in that repo + - update version number + - update sha256 + - if needed reset build number to 0 + - if needed update the requirements (easiest way to check is in hidimstat `git checkout 0.4.2` `git diff 0.4.1 -- pyproject.toml`) + - open a PR to `upstream/hidimstat-feedstock` main branch + - use checklist that will be posted in PR + - in particular it asks to post a comment asking a bot to re-render the + recipe, make sure to wait until that has finished + - then merge the PR. it can take around an hour (maybe more?) for the + package to be available from the conda-forge channel + - when it becomes available, install in a fresh env & test + - NOTE: to add new maintainers to that repo add them to the list at the end of meta.yml + +13\. Once everything is done take a break by announced the release on social network channels. diff --git a/build_package.sh b/tools/release/build_package.sh similarity index 100% rename from build_package.sh rename to tools/release/build_package.sh