python-semantic-release 9.1.1__tar.gz → 9.2.0__tar.gz

python-semantic-release-9.2.0/MANIFEST.in

@@ -0,0 +1,9 @@
+# Make sure Jinja templates are included
+recursive-include ./ *.j2
+
+# Make sure non-python files are included
+graft semantic_release/data
+
+# include docs & testing into sdist, ignored for wheel build
+graft tests/
+graft docs/

{python-semantic-release-9.1.1/python_semantic_release.egg-info → python-semantic-release-9.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-semantic-release
-Version: 9.1.1
+Version: 9.2.0
 Summary: Automatic Semantic Versioning for Python projects
 Author-email: Rolf Erik Lekang <me@rolflekang.com>
 License: MIT
@@ -21,6 +21,7 @@ Description-Content-Type: text/x-rst
 License-File: LICENSE
 License-File: AUTHORS.rst
 Requires-Dist: click<9,>=8
+Requires-Dist: click-option-group~=0.5
 Requires-Dist: gitpython<4,>=3.0.8
 Requires-Dist: requests<3,>=2.25
 Requires-Dist: jinja2<4,>=3.1.2

python-semantic-release-9.2.0/docs/Makefile

@@ -0,0 +1,183 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/python-semantic-release.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/python-semantic-release.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/python-semantic-release"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/python-semantic-release"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+
+coverage:
+	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
+
+livehtml:
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

python-semantic-release-9.2.0/docs/algorithm.rst

@@ -0,0 +1,205 @@
+.. _algorithm:
+
+Python Semantic Release's Version Bumping Algorithm
+===================================================
+
+Below is a technical description of the algorithm which Python Semantic Release
+uses to calculate a new version for a project.
+
+.. _algorithm-assumptions:
+
+Assumptions
+~~~~~~~~~~~
+
+* At runtime, we are in a Git repository with HEAD referring to a commit on
+  some branch of the repository (i.e. not in detached HEAD state).
+* We know in advance whether we want to produce a prerelease or not (based on
+  the configuration and command-line flags).
+* We can parse the tags of the repository into semantic versions, as we are given
+  the format that those Git tags should follow via configuration, but cannot
+  cherry-pick only tags that apply to commits on specific branches. We must parse
+  all tags in order to ensure we have parsed any that might apply to commits in
+  this branch's history.
+* If we can identify a commit as a ``merge-base`` between our HEAD commit and one
+  or more tags, then that merge-base should be unique.
+* We know ahead of time what ``prerelease_token`` to use for prereleases - e.g.
+  ``rc``.
+* We know ahead of time whether ``major`` changes introduced by commits
+  should cause the new version to remain on ``0.y.z`` if the project is already
+  on a ``0.`` version - see :ref:`major_on_zero <config-major-on-zero>`.
+
+.. _algorithm-implementation:
+
+Implementation
+~~~~~~~~~~~~~~
+
+1. Parse all the Git tags of the repository into semantic versions, and **sort**
+   in descending (most recent first) order according to `semver precedence`_.
+   Ignore any tags which do not correspond to valid semantic vesrions according
+   to ``tag_format``.
+
+
+2. Find the ``merge-base`` of HEAD and the latest tag according to the sort above.
+   Call this commit ``M``.
+   If there are no tags in the repo's history, we set ``M=HEAD``.
+
+3. Find the latest non-prerelease version whose tag references a commit that is
+   an ancestor of ``M``. We do this via a breadth-first search through the commit
+   lineage, starting against ``M``, and for each tag checking if the tag
+   corresponds to that commit. We break from the search when we find such a tag.
+   If no such tag is found, see 4a).
+   Else, suppose that tag corresponds to a commit ``L`` - goto 4b).
+
+4.
+    a. If no commit corresponding to the last non-prerelease version is found,
+       the entire history of the repository is considered. We parse every commit
+       that is an ancestor of HEAD to determine the type of change introduced -
+       either ``major``, ``minor``, ``patch``, ``prerelease_revision`` or
+       ``no_release``. We store this levels in a ``set`` as we only require
+       the distinct types of change that were introduced.
+    b. However, if we found a commit ``L`` which is the commit against which the
+       last non-prerelease was tagged, then we parse only the commits from HEAD
+       as far back as ``L``, to understand what changes have been introduced
+       since the previous non-prerelease. We store these levels - either
+       ``major``, ``minor``, ``patch``, ``prerelease_revision``, or
+       ``no_release``, in a set, as we only require the distinct types of change
+       that were introduced.
+
+    c. We look for tags that correspond to each commit during this process, to
+       identify the latest pre-release that was made within HEAD's ancestry.
+
+5. If there have been no changes since the last non-prerelease, or all commits
+   since that release result in a ``no_release`` type according to the commit
+   parser, then we **terminate the algorithm.**
+
+6. If we have not exited by this point, we know the following information:
+
+  * The latest version, by `semver precedence`_, within the whole repository.
+    Call this ``LV``. This might not be within the ancestry of HEAD.
+  * The latest version, prerelease or non-prerelease, within the whole repository.
+    Call this ``LVH``. This might not be within the ancestry of HEAD.
+    This may be the same as ``LV``.
+  * The latest non-prerelease version within the ancestry of HEAD. Call this
+    ``LVHF``. This may be the same as ``LVH``.
+  * The most significant type of change introduced by the commits since the
+    previous full release. Call this ``level``
+  * Whether or not we wish to produce a prerelease from this version increment.
+    Call this a boolean flag, ``prerelease``. (Assumption)
+  * Whether or not to increment the major digit if a major change is introduced
+    against an existing ``0.`` version. Call this ``major_on_zero``, a boolean
+    flag. (Assumption)
+
+  Using this information, the new version is decided according to the following
+  criteria:
+
+  a. If ``LV`` has a major digit of ``0``, ``major_on_zero`` is ``False`` and
+     ``level`` is ``major``, reduce ``level`` to ``minor``.
+
+  b. If ``prerelease=True``, then
+
+     i. Diff ``LV`` with ``LVHF``, to understand if the ``major``, ``minor`` or
+        ``patch`` digits have changed. For example, diffing ``1.2.1`` and
+        ``1.2.0`` is a ``patch`` diff, while diffing ``2.1.1`` and ``1.17.2`` is
+        a ``major`` diff. Call this ``DIFF``
+
+     ii. If ``DIFF`` is less semantically significant than ``level``, for example
+         if ``DIFF=patch`` and ``level=minor``, then
+
+         1. Increment the digit of ``LVF`` corresponding to ``level``, for example
+            the minor digit if ``level=minor``, setting all less significant
+            digits to zero.
+
+         2. Add ``prerelease_token`` as a suffix result of 1., together with a
+            prerelease revision number of ``1``. Return this new version and
+            **terminate the algorithm.**
+
+         Thus if ``DIFF=patch``, ``level=minor``, ``prerelease=True``,
+         ``prerelease_token="rc"``, and ``LVF=1.1.1``,
+         then the version returned by the algorithm is ``1.2.0-rc.1``.
+
+     iii. If ``DIFF`` is semantically less significant than or equally
+          significant to ``level``, then this means that the significance
+          of change introduced by ``level`` is already reflected in a
+          prerelease version that has been created since the last full release.
+          For example, if ``LVHF=1.1.1``, ``LV=1.2.0-rc.1`` and ``level=minor``.
+
+          In this case we:
+
+          1. If the prerelease token of ``LV`` is different from
+             ``prerelease_token``, take the major, minor and patch digits
+             of ``LV`` and construct a prerelease version using our given
+             ``prerelease_token`` and a prerelease revision of ``1``. We
+             then return this version and **terminate the algorithm.**
+
+             For example, if ``LV=1.2.0-rc.1`` and ``prerelease_token=alpha``,
+             we return ``1.2.0-alpha.1``.
+
+          2. If the prerelease token of ``LV`` is the same as ``prerelease_token``,
+             we increment the revision number of ``LV``, return this version, and
+
+             **terminate the algorithm.**
+             For example, if ``LV=1.2.0-rc.1`` and ``prerelease_token=rc``,
+             we return ``1.2.0-rc.2``.
+
+  c. If ``prerelease=False``, then
+
+    i. If ``LV`` is not a prerelease, then we increment the digit of ``LV``
+       corresponding to ``level``, for example the minor digit if ``level=minor``,
+       setting all less significant digits to zero.
+       We return the result of this and **terminate the algorithm**.
+
+    ii. If ``LV`` is a prerelease, then:
+
+      1. Diff ``LV`` with ``LVHF``, to understand if the ``major``, ``minor`` or
+         ``patch`` digits have changed. Call this ``DIFF``
+
+      2. If ``DIFF`` is less semantically significant than ``level``, then
+
+        i. Increment the digit of ``LV`` corresponding to ``level``, for example
+           the minor digit if ``level=minor``, setting all less significant
+           digits to zero.
+
+        ii. Remove the prerelease token and revision number from the result of i.,
+            ("Finalize" the result of i.) return the result and **terminate the
+            algorithm.**
+
+            For example, if ``LV=1.2.2-alpha.1`` and ``level=minor``, we return
+            ``1.3.0``.
+
+      3. If ``DIFF`` is semantically less significant than or equally
+         significant to ``level``, then we finalize ``LV``, return the
+         result and **terminate the algorithm**.
+
+.. _semver precedence: https://semver.org/#spec-item-11
+
+.. _algorithm-complexity:
+
+Complexity
+~~~~~~~~~~
+
+**Space:**
+
+A list of parsed tags takes ``O(number of tags)`` in space. Parsing each commit during
+the breadth-first search between ``merge-base`` and the latest tag in the ancestry
+of HEAD takes at worst ``O(number of commits)`` in space to track visited commits.
+Therefore worst-case space complexity will be linear in the number of commits in the
+repo, unless the number of tags significantly exceeds the number of commits
+(in which case it will be linear in the number of tags).
+
+**Time:**
+
+Assuming using regular expression parsing of each tag is a constant-time operation,
+then the following steps contribute to the time complexity of the algorithm:
+
+* Parsing each tag - ``O(number of tags)``
+* Sorting tags by `semver precedence`_ -
+  ``O(number of tags * log(number of tags))``
+* Finding the merge-base of HEAD and the latest release tag -
+  ``O(number of commits)`` (worst case)
+* Parsing each commit and checking each tag against each commit -
+  ``O(number of commits) + O(number of tags * number of commits)``
+  (worst case)
+
+Overall, assuming that the number of tags is less than or equal to the number
+of commits in the repository, this would lead to a worst-case time complexity
+that's quadratic in the number of commits in the repo.

python-semantic-release-9.2.0/docs/automatic-releases/cronjobs.rst

@@ -0,0 +1,41 @@
+.. _cronjobs:
+
+Publish with cronjobs
+~~~~~~~~~~~~~~~~~~~~~
+
+This is for you if for some reason you cannot publish from your CI or you would like releases to
+drop at a certain interval. Before you start, answer this: Are you sure you do not want a CI to
+release for you? (high version numbers are not a bad thing).
+
+The guide below is for setting up scheduled publishing on a server. It requires that the user
+that runs the cronjob has push access to the repository and upload access to an artifact repository.
+
+1. Create a virtualenv::
+
+    virtualenv semantic_release -p `which python3`
+
+2. Install python-semantic-release::
+
+    pip install python-semantic-release
+
+3. Clone the repositories you want to have scheduled publishing.
+3. Put the following in ``publish``::
+
+    VENV=semantic_release/bin
+
+    $VENV/pip install -U pip python-semantic-release > /dev/null
+
+    publish() {
+      cd $1
+      git stash -u # ensures that there is no untracked files in the directory
+      git fetch && git reset --hard origin/master
+      $VENV/semantic-release version && $VENV/semantic-release publish
+      cd ..
+    }
+
+    publish <package1>
+    publish <package2>
+
+4. Add cronjob::
+
+    /bin/bash -c "cd <path> && source semantic_release/bin/activate && ./publish 2>&1 >> releases.log"

python-semantic-release-9.2.0/docs/automatic-releases/github-actions.rst

@@ -0,0 +1,104 @@
+.. _github-actions:
+
+Setting up python-semantic-release on GitHub Actions
+====================================================
+
+Python Semantic Release includes a GitHub Action which runs the ``version`` and
+``publish`` commands. The repository is set to ``PyPI``. You can read the full set
+of inputs available, and their descriptions in the `action definition`_.
+
+Your project's configuration file will be used as normal.
+
+The GitHub Action provides the following outputs:
+
++-------------+-----------------------------------------------------------+
+| Output      | Description                                               |
++-------------+-----------------------------------------------------------+
+| released    | "true" if a release was made, "false" otherwise           |
++-------------+-----------------------------------------------------------+
+| version     | The newly released version if one was made, otherwise     |
+|             | the current version                                       |
++-------------+-----------------------------------------------------------+
+| tag         | The Git tag corresponding to the "version" output. The    |
+|             | format is dictated by your configuration.                 |
++-------------+-----------------------------------------------------------+
+
+.. _action definition: https://github.com/python-semantic-release/python-semantic-release/blob/master/action.yml
+
+Example Workflow
+----------------
+
+.. code:: yaml
+
+   name: Semantic Release
+
+   on:
+     push:
+       branches:
+         - master
+
+   jobs:
+     release:
+       runs-on: ubuntu-latest
+       concurrency: release
+       permissions:
+         id-token: write
+         contents: write
+
+       steps:
+       - uses: actions/checkout@v3
+         with:
+           fetch-depth: 0
+
+       - name: Python Semantic Release
+         uses: python-semantic-release/python-semantic-release@master
+         with:
+           github_token: ${{ secrets.GITHUB_TOKEN }}
+
+``concurrency`` is a
+`beta feature of GitHub Actions <https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idconcurrency>`_
+which disallows two or more release jobs to run in parallel. This prevents race
+conditions if there are multiple pushes in a short period of time.
+
+If you would like to use Python Semantic Release to create GitHub Releases against
+your repository, you will need to allow the additional ``contents: write`` permission.
+More information can be found in the `permissions for GitHub Apps documentation`_
+
+.. _permissions for GitHub Apps documentation: https://docs.github.com/en/rest/overview/permissions-required-for-github-apps?apiVersion=2022-11-28#contents
+
+.. warning::
+  You must set ``fetch-depth`` to 0 when using ``actions/checkout@v2``, since
+  Python Semantic Release needs access to the full history to determine whether
+  a release should be made.
+
+.. warning::
+  The ``GITHUB_TOKEN`` secret is automatically configured by GitHub, with the
+  same permissions as the user who triggered the workflow run. This causes
+  a problem if your default branch is protected.
+
+  You can work around this by storing an administrator's Personal Access Token
+  as a separate secret and using that instead of ``GITHUB_TOKEN``. In this
+  case, you will also need to pass the new token to ``actions/checkout`` (as
+  the ``token`` input) in order to gain push access.
+
+Multiple Projects
+-----------------
+
+If you have multiple projects stored within a single repository (or your
+project is not at the root of the repository), you can pass the
+``directory`` input. The step can be called multiple times to release
+multiple projects.
+
+.. code:: yaml
+
+   - name: Release Project 1
+     uses: python-semantic-release/python-semantic-release@master
+     with:
+       directory: ./project1
+       github_token: ${{ secrets.GITHUB_TOKEN }}
+
+   - name: Release Project 2
+     uses: python-semantic-release/python-semantic-release@master
+     with:
+       directory: ./project2
+       github_token: ${{ secrets.GITHUB_TOKEN }}

python-semantic-release-9.2.0/docs/automatic-releases/index.rst

@@ -0,0 +1,26 @@
+.. _automatic:
+
+Automatic Releases
+------------------
+
+The key point with using this package is to automate your releases and stop worrying about
+version numbers. Different approaches to automatic releases and publishing with the help of
+this package can be found below. Using a CI is the recommended approach.
+
+.. _automatic-guides:
+
+Guides
+^^^^^^
+
+.. toctree::
+    travis
+    github-actions
+    cronjobs
+
+.. _automatic-github:
+
+Configuring push to Github
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+In order to push to Github and post the changelog to Github the environment variable
+:ref:`GH_TOKEN <index-creating-vcs-releases>` has to be set. It needs access to the
+``public_repo`` scope for public repositories and ``repo`` for private repositories.

python-semantic-release-9.2.0/docs/automatic-releases/travis.rst

@@ -0,0 +1,53 @@
+Setting up python-semantic-release on Travis CI
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This guide expects you to have activated the repository on Travis CI.
+If this is not the case, please refer to `Travis documentation`_ on how to do that.
+
+1. Add python-semantic-release settings
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+See :doc:`../configuration` for details on how to configure Python Semantic Release.
+Make sure that at least you have set :ref:`config-version-variables` before continuing.
+
+2. Add environment variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+You will need to set up an environment variable in Travis. An easy way to do that
+is to go to the settings page for your package and add it there. Make sure that the
+secret toggle is set correctly.
+
+You need to set the :ref:`GH_TOKEN <index-creating-vcs-releases>` environment
+variable with a personal access token for Github. It will need either ``repo`` or
+``public_repo`` scope depending on whether the repository is private or public.
+
+More information on how to set environment variables can be found on
+`Travis documentation on environment variables`_.
+
+3. Add travis configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The following should be added to your ``.travis.yml`` file.
+
+.. code-block:: yaml
+
+    after_success:
+    - git config --global user.name "semantic-release (via TravisCI)"
+    - git config --global user.email "semantic-release@travis"
+    - pip install python-semantic-release
+    - semantic-release version && semantic-release publish
+
+
+The first line tells Travis that we want to run the listed tasks after a successful build.
+The two first lines in after_success will configure git so that python-semantic-release
+will be able to commit on Travis. The third installs the latest version of python-semantic-release.
+The last will run the publish command, which will publish a new version if the changes
+indicate that one is due.
+
+
+4. Push some changes
+^^^^^^^^^^^^^^^^^^^^
+You are now ready to release automatically on Travis CI on every change to your master branch.
+
+Happy coding!
+
+.. _Travis documentation: https://docs.travis-ci.com/
+.. _Travis documentation on environment variables: https://docs.travis-ci.com/user/environment-variables/#Defining-Variables-in-Repository-Settings