Package: release-tools
Release ToolsSet of tools to generate Python releases.With this package, Python maintainers are able to automate
many of the boring and time consuming tasks related with
packages and releases.These tools are based in the way GitLab project generates its
releases. You have more information about their motivationhere.This software is licensed under GPL3 or later.FeaturesThis package allows us to:Automate the creation of release notesBump up the release version based on the release notesPublish a release in a Git repositoryRequirementsPython >= 3.7Poetry >= 1.0InstallationTo install the release tools from the source code you'll need
to installpoetry. We usepoetryfor dependency management and packaging. You can install it
following itsdocumentation.Once you have installed it, you can download the source code with git:# Get release-tools source code
$ git clone https://github.com/Bitergia/release-toolsMove to the directory and install the software and the dependencies:$ cd release-tools
$ poetry installWorkflowTogether with these tools, this package provides anopinionated
wayto generate the release of a Python package. We think
releases must be automated and provide useful information
to end users so they can understand better the changes between
versions. Our tools fulfill those requirements.There are also someassumptionsto take into account:We use git repositories.We usesemantic versioningfor numbering our packages.Version numbers are defined in the variable__version__which is
stored on a file called_version.py. This file must be tracked on the git
repository.We usepoetryand the filepyproject.toml(seePEP518) to manage
build system dependencies. If you don't have this file, you can use
the commandpoetry initto create it from scratch. This file must
be tracked on the git repository.Theworkflowis defined by the next steps:changelog -> semverup -> notes -> publishDevelopers usechangelogscript to generate changelogentry
notes. They contain basic information about their changes in
the code (e.g a new feature; a fixed bug). The notes shouldexplainthe change to a reader who haszero contextabout
software details.Werecommendto create one of these entries for each pull
request or merge request.These notes are stored under the directoryreleases/unreleased.Once we are ready to create a new release, we callsemverup.
It will increase theversionaccording to semantic versioning
and the type of changelog entries generated between releases.When the version is increased, we runnotesto generate therelease notesusing the unreleased changelog entries.Finally, wepublishthe release in the Git repository creating
acommitthat will contain the new release notes and the new
version files. Atagis also created with the new version number.
To do it, we call topublishscript. This script also removes
the entries inreleased/unreleaseddirectory.This is an example of the basic usage:# Create some changelog entries
$ changelog -t "Fix bug #666" -c fixed
Changelog entry 'fix-bug-#666.yml' created

$ changelog -t "Add support for deleting entries" -c added
Changelog entry 'add-support-for-deleting-entries.yml' created

# Increase the version number
$ semverup
0.2.0

# Generate the release notes
$ notes "WebApp" 0.2.0
Release notes file '0.2.0.md' created

# Publish the release in a public repository
$ publish 0.2.0 "John Smith <jsmith@example.com>" --push origin
Cleaning directories...done
Adding files to the release commit...done
Creating release commit...done
Publishing release in origin...doneToolschangelogThis interactive tool creates note entries about the changes in
the code. Developers can use this tool to create these notes that
will be included in the changelog or in the release notes.
You will need to run this script inside of the Git where you store
the project.It will guide you to create a new entry. You can select the title
and the type of the change.>> Please specify the title of your change: Fix bug #666>> Please specify the category of your change

1. New feature (added)
2. Bug fix (fixed)
3. Breaking change (changed)
4. New deprecation (deprecated)
5. Feature removal (removed)
6. Security fix (security)
7. Performance improvement (performance)
8. Dependencies updated (dependency)
9. Other (other)

: 2Each category updates a different version number:Major version:changedandremoved.Minor version:added,deprecated,security,performanceandother.Patch version:fixedanddependency.At the end of the process, a text editor will open to let you review
the entry and make the final changes. The editor will be the default
defined in your system.title: 'Fix bug #666'
category: fixed
author: John Smith <jsmith@example.com>
issue: 666
notes: >
  The bug was making impossible to cast a spell on
  a magician.New entries will be stored in "releases/unreleased" directory.
This directory must be available under the Git root path.Changelog entry 'fix-bug-#666.yml' createdIf you don't want to create a new entry and see only the final result,
please active '--dry-run' flag.$ changelog --dry-runYou can skip some parts of the process providing information
in advance such as the title (-t) or the category (-c)
of the entry.$ changelog -t "Fix bug #666" -c fixedsemverupThis script increments the version number following semver specification
and using the note entries generated withchangelogtool.$ semverup
0.2.0notesWhen you run this script, it will generate the release notes of the
package tracked by the current Git repository.You'll need to provide thenameof the package and theversionof the new release. The script will generate a Markdown document
under thereleasesdirectory using the changelog entries stored
onreleases/unreleased. Take into account the argumentnameis only used as the title of the document.$ notes "MyApp" 0.2.0
Release notes file '0.2.0.md' createdChangelog entries included in the release notes are moved to a new
directory in 'unreleased/processed'. If you are running multiple
release candidates, and you don't want to include the same notes in
successive release candidates, use the flag '--pre-release'.If you also want to add the content of these release notes to theNEWSfile, use the flag--news.$ notes "MyApp" 0.2.0 --news
Release notes file '0.2.0.md' created
News file updated to 0.2.0If you just want to see the final result of the notes
but not generate a new file, please activate--dry-runflag.$ notes "MyApp" 0.2.0 --dry-run
## MyApp 0.2.0 - (2020-03-04)

**Bug fixes:**

 * Fix bug #666
   The bug was making impossible to cast a spell on
   a magician.If you want to add the contributor names of these release notes to the
AUTHORS file, use the flag--authors.$ notes "MyApp" 0.2.0 --authors
Release notes file '0.2.0.md' created
Authors file updatedpublishThis script will generate a new release in the repository.
This will consist on creating a commit and a tag with the
new release notes and the updated version files.To run it, you'll need to provide the version number and
the author of the new release.$ publish 0.2.0 "Jonh Smith <jsmith@example.com>"
Cleaning directories...done
Adding files to the release commit...done
Creating release commit...doneBy default the command doesn't push the commit release to a
remote repository. To force it, use the parameter--pushincluding the name of the remote where commits will be pushed.$ publish 0.2.0 "John Smith <jsmith@example.com>" --push origin
Cleaning directories...done
Adding files to the release commit...done
Creating release commit...done
Publishing release in origin...doneIt is also possible to push only the commit release and its tag.
To do so, set--only-pushtogether with--pushoption.$ publish 0.2.0 "John Smith <jsmith@example.com>" --push origin --only-push
Publishing release in origin...doneTroubleshootingHow can I change the default editor used bychangelog?By default,changelogwill use the editor defined in theEDITORenvironment variable. You can define your own editor updating this
variable.export EDITOR=/bin/nanoIf this variable doesn't exist it will try withvimornanoin that order.What's the format of the changelog entries?Changelog entries useYAML format.Remember you can write blocks of text using>character at the beginning
of each block. See the next example:title: 'Example of notes'
category: fixed
author: John Smith <jsmith@example.com>
issue: 1
notes: >
  Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
  tempor incididunt ut labore et dolore magna aliqua.
  Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi
  ut aliquip ex ea commodo consequat.Error: version file not foundThe tools did not found a_version.pyfile. This file must also
be tracked on your repository. It must contain a variable named__version__. The value must be a string following semantic
versioning format.$ cat _version.py
__version__ = "3.6.5"Error: version number '<version>' in '<filepath>' is not a valid semver stringThe format of the version number is invalid. We use semantic
versioning format to set version numbers. The value must be astr.
Change the version number and check thesemantic versioning rulesin case of doubt.Error: pyproject file not foundThe tools did not found apyproject.tomlfile. This file must also
be tracked on your repository. It contains information needed bypoetryto build the software package. If you don't have this file
you can create a new one usingpoetry init.$ poetry initError: pathspec '<filepath>' did not match any files; code error: 128The file<filepath>must be tracked by your git repository. Add it to
your repo. Usually you'll get this error if you forgot to add your
changelog entry notes to the repository.Error: tag '<tag>' already exists; code error: 128If you have a existing tag with the same version, you can expect
this error. You can delete the tag usinggit tag -d versionand
create the release commit again using publish.$ git tag -d 0.2.0
$ publish 0.2.0 "John Smith <jsmith@example.com>" --push originError: error: src refspec '<branch>' does not match anyYou can expect this error if you are not usingmasteras your default
branch. You can change this in the codebase (push method of the publish.py)
if you are using any other branch as default.If you are usingmainas default branch, changemastertomain.-   project.repo.push(remote, 'master')
+   project.repo.push(remote, 'main')You can usepublishand set--only-pushtogether with--pushoption
as the release is committed but not pushed yet.$ publish 0.2.0 "John Smith <jsmith@example.com>" --push origin --only-push
Publishing release in origin...doneError: Authentication failed for '<github-url>'; code error: 128If the release commit is created and you failed to publish the release
because of invalid credentials for git, you can usepublishand
set--only-pushtogether with--pushoption as the release is committed
but not pushed yet.$ publish 0.2.0 "John Smith <jsmith@example.com>" --push origin --only-push
Publishing release in origin...doneLicenseLicensed under GNU General Public License (GPL), version 3 or later.