diff options
Diffstat (limited to 'debian/uncrustify-trinity/uncrustify-trinity-0.78.1/release-process.rst')
| -rw-r--r-- | debian/uncrustify-trinity/uncrustify-trinity-0.78.1/release-process.rst | 363 |
1 files changed, 0 insertions, 363 deletions
diff --git a/debian/uncrustify-trinity/uncrustify-trinity-0.78.1/release-process.rst b/debian/uncrustify-trinity/uncrustify-trinity-0.78.1/release-process.rst deleted file mode 100644 index 469a4dff..00000000 --- a/debian/uncrustify-trinity/uncrustify-trinity-0.78.1/release-process.rst +++ /dev/null @@ -1,363 +0,0 @@ -============================ - Uncrustify Release Process -============================ - -.. Update the date in the next line when editing this document! - -*This document was last updated on 2023-11-20, for Uncrustify 0.78.1.* - -This document uses "0.1.2" throughout as an example version number. -Whenever you see this, you should substitute the version number -of the new release being prepared. - -Paths are specified in git syntax, i.e. ``:/`` is the repository root. - -Requirements -============ - -This document assumes you are using a Linux-based OS. -While it should be possible to cut a release on Windows, -using e.g. the `Git for Windows SDK <https://gitforwindows.org/>`_ -or a MinGW_ environment, the names and/or arguments to some commands -may be different. - - -In addition to the build and test requirements for Uncrustify itself -(CMake, a C++ compiler, Python, git), you will also need: - -- tar -- python3-git -- Binutils-mingw-w64 -- Gcc-mingw-w64 -- G++-mingw-w64 -- zip -- wget (optional) -- scp (to update documentation on the SourceForge page) - -Using packages provided by your OS distribution is *strongly* recommended. -(Exact package names may vary depending on your distribution.) -Examples use ``wget`` to download files via command line, -but any mechanism of obtaining files over HTTPS may be employed. - -Preparing a Candidate -===================== - -The first step, obviously, is deciding to make a release. -Prior to making a release, verify that the repository is in a stable state -and that all CI (continuous integration - AppVeyor) has passed. -This should ensure all tests pass and building -(including cross-compiling) for Windows is working. - -Once the release process is started, -only pull requests needed to fix critical bugs, -or related to the release process, should be accepted. -(This will minimize the need to redo or repeat work -such as updating the documentation, especially the change log.) - -To start the release process, first check that: - -- You are on the ``master`` branch -- Your local clone is up to date -- ``CMAKE_BUILD_TYPE`` is set to ``Release`` (or ``RelWithDebInfo``) -- Your build is up to date -- check the list of authors with scripts/prepare_list_of_authors.sh - -You might need a new PAT for your account, for your admin-account. -See: -https://github.blog/2020-12-15-token-authentication-requirements-for-git-operations/ -https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token - login with an admin account at https://github.com/uncrustify/uncrustify - on the right, click on the photo - scroll down to "Settings" - on the left, scroll down to "Developer settings", and click - on the left, click on "Personal access tokens" - choose "Tokens (classic), click - if necessary "Delete" expired token(s) - click on "Generate new token" - choose "Generate new token (classic)", click - choose a "what's this token for" - click on "repo" - scroll down to bottom and click on "Generate token" -Make sure to copy your personal access token now. You won’t be able to see it again! - copy the token "ghp_otx****" - and substitute in the file .git/config for [remote "origin"] - "url = https://gmaurel:ghp_otxZ****" - -Then, run:: - - $ scripts/release_tool.py init - $ scripts/release_tool.py update path/to/uncrustify - -(Replace ``path/to/uncrustify`` with the path to the Uncrustify executable -you just built, e.g. ``build/uncrustify``.) - -This will create a branch for the release candidate -and perform some automated updates to various files. -With no arguments, ``init`` will prompt you for the new version number, -defaulting to ``x.(y+1).0``, where ``x.y.z`` is the previous release. -The ``--version`` argument may also be used to specify the version -(e.g. if the script will not be able to prompt for input). - -After, you should check that the following files -show the correct version number and option count: - -- ``:/CMakeLists.txt`` (version number only; look for ``UNCRUSTIFY_VERSION``) -- ``:/package.json`` (version number only; you'll see it, the file is tiny) -- ``:/README.md`` (look for "options as of version") -- ``:/documentation/htdocs/index.html`` (look for "options as of version") - -(Note that ``uncrustify`` itself will not show the new version number -until the final release has been tagged.) - -Update Documentation -==================== - -Update ``:/ChangeLog``. -There is a helper script, ``:/scripts/gen_changelog.py``, -that can help extract new options since the previous release: - -.. code:: - - $ scripts/gen_changelog.py uncrustify-0.0.0 - -Replace ``0.0.0`` with the version of the *previous* release. -This will generate a bunch of output like:: - - 0123456789abcdef0123456789abcdef01234567 - Added : better_name Jan 13 1970 - Removed : poor_name Jan 13 1970 - fedcba9876543210fedcba9876543210fedcba98 - Added : new_option_1 Jan 18 1970 - Added : new_option_2 Jan 18 1970 - -Your goal is to turn the "raw" output into something like this:: - - Deprecated options: - - poor_name Jan 13 1970 - Renamed to better_name - - New options: - - new_option_1 Jan 18 1970 - - new_option_1 Jan 18 1970 - -To accomplish this, you will need to inspect any removed options, -possibly consulting the commits in which they were removed, -to determine the reason for deprecation and what replacement is recommended. -(Note that it may not be as simple as "use X instead".) -Also watch for options that were added and subsequently renamed -since the last release. (This has happened a few times. -In such cases, the new name should show up as an ordinary "new" option, -and the old name should be entirely omitted from the change log.) - -It helps to copy the output to a scratch file for editing. -Move deprecated options to the top and add a "Deprecated options:" header, -then add a "New options:" header in front of what's left, -and remove the commit SHAs (``sed -r '/^[[:xdigit:]]{40}/d`` -if you don't want to do it by hand). -Then, check that the options are in order by date; -date of authorship vs. date of merge may cause discrepancies. -Finally, replace occurrences of ``\w+ +:`` with ``-`` -(if your editor supports regular expressions; -otherwise you can individually replace ``Added :`` and ``Removed :``). - -Add a new release header (don't forget to add the date!) to the change log -and insert the list of option changes as created above. -Also fill in the list of resolved issues, new keywords (if any), -as well as any other changes that need to be mentioned. - -If any command line arguments have been added or changed, -including descriptions for the same, check to see if -``:/man/uncrustify.1.in`` needs to be updated. -(Hopefully this happened when the source was changed!) - -Finalize the Code Changes -========================= - -Inspect your working tree. -Use ``git add -p`` to stage the changes made to the documentation -and other artifacts that contain version-dependent information. -Verify that only desired changes are staged, -and that your working tree is otherwise clean. - -Now is a good time to recheck -that everything builds, and that all the tests pass. -This is also a good time to manually test 32- and 64-bit builds. - -When you are ready, commit the changes using: - -.. code:: - - $ scripts/release_tool.py commit - -(If you prefer, you can also commit the changes manually; -the script just fills in the commit message for you.) - -Submit and Tag the Release -========================== - -Push the release candidate branch to GitHub, and create a pull request. -Once the pull request is merged, tag the release using: -Make sure, the file .git/config has the right 'admin' value: -[remote "origin"] - url = https://<admin account>:<PAT>@github.com/uncrustify/uncrustify.git -Check it with: -$ git config --local --get remote.origin.url - -.. code:: - - $ scripts/release_tool.py tag - -Note that this will only work if the merge of the release candidate -is the most recent commit upstream. -Otherwise, the merge commit must be specified by using the ``-c`` option. - -(Tagging the release does not need to be done on any particular branch. -The command will not affect or look at your work tree at all.) - -Create Binaries -=============== - -Now that the release is published, grab a copy of the sources from GitHub: - -.. code:: - - $ wget https://github.com/uncrustify/uncrustify/archive/uncrustify-0.1.2.zip - $ unzip -e uncrustify-0.1.2.zip - -Next, build the 32- and 64-bit Windows binaries: - -.. code:: - - $ cd /path/to/uncrustify-uncrustify-0.1.2 - $ mkdir buildwin-32 - $ cd buildwin-32 - $ cmake -G Ninja \ - -DCMAKE_BUILD_TYPE=Release \ - -DCMAKE_TOOLCHAIN_FILE=../cmake/Toolchain-mingw32.cmake \ - -DCMAKE_EXE_LINKER_FLAGS="-static -s" \ - .. - $ ninja - $ cpack - -.. code:: - - $ cd /path/to/uncrustify-uncrustify-0.1.2 - $ mkdir buildwin-64 - $ cd buildwin-64 - $ cmake -G Ninja \ - -DCMAKE_BUILD_TYPE=Release \ - -DCMAKE_TOOLCHAIN_FILE=../cmake/Toolchain-mingw64.cmake \ - -DCMAKE_EXE_LINKER_FLAGS="-static -s" \ - .. - $ ninja - $ cpack - -Create a tarball: - -.. code:: - - $ cd /path/to/uncrustify - $ git archive -o uncrustify-0.1.2.tar.gz --prefix=uncrustify-0.1.2/ uncrustify-0.1.2 -TODO: find the best strategie... - -(If you don't have Ninja_, or just don't want to use it for whatever reason, -omit ``-G Ninja`` and run ``make`` instead of ``ninja``.) - -This is also a good time to test the tagged build on Linux: - -.. code:: - - $ wget https://github.com/uncrustify/uncrustify/archive/uncrustify-0.1.2.tar.gz - $ tar xzf uncrustify-0.1.2.tar.gz - $ cd uncrustify-uncrustify-0.1.2 - $ mkdir build - $ cd build - $ cmake -G Ninja -DCMAKE_BUILD_TYPE=Release .. - $ ninja - $ ctest - $ ./uncrustify --version - -Create a release on github -========================== - -- Login with an admin account at https://github.com/uncrustify/uncrustify -- Navigate to https://github.com/uncrustify/uncrustify/releases and click on - the "Draft a new release" button at the top of the page -- Select the corresponding release tag under the "Choose a tag" combobox -- Add the release version under "Release title" as "Uncrustify 0.xx.y" -- Add release text in describing section. It is recommended to copy the text - from previous releases and update the related files -- Upload the Windows binaries and the source code zip/tarball files in the section - "Attach binaries by dropping them here or selecting them": these will show up as - "Assets" under the release text. -- Publish the release by clicking on the "Publish release" button. - -Upload to SourceForge -===================== - -- Login as admin under https://sourceforge.net/projects/uncrustify/ -- Change to https://sourceforge.net/projects/uncrustify/files/ -- "Add Folder"; the name should be e.g. "uncrustify-0.1.2" -- Navigate to the new folder - (e.g. https://sourceforge.net/projects/uncrustify/files/uncrustify-0.1.2/) -- "Add File"; upload the following files - (adjusting for the actual version number): - - - README.md - - uncrustify-0.1.2.tar.gz - - buildwin-32/uncrustify-0.1.2_f-win32.zip - - buildwin-64/uncrustify-0.1.2_f-win64.zip - -- "Done" -- Upload the documentation: - - .. code:: - - $ scp -r documentation/htdocs/* ChangeLog \ - USER,uncrustify@web.sourceforge.net:htdocs/ - -- Use the web interface (file manager) to create the release folder - and upload the files to SourceForge. - -Announce the Release (Optional) -=============================== - -The new release is live! Spread the word! Consider these ideas: - -- Create a news item. -- Update freshmeat.net project. - -Release Checklist -================= - -The following list serves as a quick reference for making a release. -These items are explained in greater detail above. - -#. Verify that CI passes - -#. Use ``release_tool.py`` to initialize the release - and perform automated updates. Check: - - #. ``:/CMakeLists.txt`` - #. ``:/package.json`` - #. ``:/README.md`` - #. ``:/documentation/htdocs/index.html`` - -#. Update documentation as needed: - - #. ``:/ChangeLog`` - #. ``:/man/uncrustify.1.in`` - -#. Stage changes. -#. Test everything again. -#. Finalize the code changes. -#. Push to GitHub and create a merge request. -#. Tag the merged release branch. -#. Create Windows (32- and 64-bit) binaries. -#. Run a test build on Linux. -#. Upload the release and documentation to SourceForge. -#. Announce the release! - -.. _MinGW: http://www.mingw.org/ -.. _GitPython: https://github.com/gitpython-developers/GitPython -.. _Ninja: https://ninja-build.org/ |