backstage.tasks

2022-09-15 (Alex Rustic)
This 'backstage.tasks' file is written for Python projects.
Put this file in the root directory of your Python project.

You will need to install 'backstage', 'setupinit', and 'buildver':
    $ pip install backstage
    $ pip install setupinit
    $ pip install buildver

Once installed, run:
    $ cd /path/to/project
    $ backstage --help

Visit https://github.com/pyrustic/backstage


------------------------------------------------------------------


[build]
$ buildver build {ARGS}


[build.test]
assert 1 == 1


------------------------------------------------------------------


[check]
$ buildver check


[check.test]
assert 1 == 1


------------------------------------------------------------------


[clean]
pass


[clean.test]
assert 1 == 1


------------------------------------------------------------------


[gendoc]
$ hyperdoc build


[gendoc.test]
assert 1 == 1


------------------------------------------------------------------


[gitcommit]
default message
set message = {ARGS[0]}
if message == EMPTY
    set message = `Update`
$ git add .
$ git commit -m {message}


[gitcommit.test]
assert 1 == 1


------------------------------------------------------------------


[gitinit]
default origin
set origin = {ARGS[0]}
if origin == EMPTY
    > origin : `Origin: `
$ git init
$ git remote add origin {origin}


[gitinit.test]
assert 1 == 1


------------------------------------------------------------------


[gitpush]
default project_version
set project_version = {ARGS[0]}
if project_version == EMPTY
    $ git push origin master
else
    $ git push origin master tag {project_version}
return R


[gitpush.test]
assert 1 == 1


------------------------------------------------------------------


[init]
$ setupinit init


[init.test]
assert 1 == 1


------------------------------------------------------------------


[release]
interface with buildver
set project_dir = {CWD}
call buildver.get_version(project_dir)
set project_version = {R}
if project_version == EMPTY
    : Failed to get the project version.
    : Release cancelled.
    return
: Project version: {project_version}
:
: == Documentation generation ==
:
& gendoc
:
: == Commit changes ==
:
& gitcommit
:
: == Git tag ==
:
$ git tag {project_version}
:
: == Build distribution package ==
:
& build {ARGS}
:
: == Commit changes ==
:
& gitcommit
:
: == Git push ==
:
& _looped_task gitpush {project_version}
:
: == Upload package to PyPI ==
:
& _looped_task upload2pypi
:
: Goodbye !


[release.test]
assert 1 == 1


------------------------------------------------------------------


[test]
$ python -m unittest discover -f -s tests -t .


[test.test]
assert 1 == 1


------------------------------------------------------------------


[upload2pypi]
$ twine upload --skip-existing dist/*
return R


[upload2pypi.test]
assert 1 == 1


------------------------------------------------------------------


[_looped_task]
# take a task as argument
# and ensure it exits with success
# (if the user is ok with it)
set success = {FALSE}
while success == FALSE
    & {ARGS}
    if R == 0
        set success = {TRUE}
    else
        set success = {FALSE}
    if success == FALSE
        :
        & _ask_confirmation "Repeat the failed subtask (y/N): "
        :
        if R == 0
            break


------------------------------------------------------------------


[_ask_confirmation]
# ask for confirmation
# returns 1 if True, else 0
default message
set message = {ARGS[0]}
> result : {message}
set yes = `y`
if result == yes
    return 1
return 0


------------------------------------------------------------------


[build.help]
Build the Python project

Usage:
    backstage build
    backstage build then <next_version>

Example:
    backstage build then 3.0.0
    backstage build then +maj

Under the hood, the package 'buildver' is used.


------------------------------------------------------------------


[check.help]
Get the project version and latest build information

Usage:
    backstage check

Under the hood, the package 'buildver' is used.


------------------------------------------------------------------


[clean.help]
Clean the project directory

Usage:
    backstage clean


------------------------------------------------------------------


[gendoc.help]
Generate the project documentation

Usage:
    backstage gendoc


------------------------------------------------------------------


[gitcommit.help]
Save your changes to the local repository

Usage:
    backstage gitcommit
    backstage gitcommit <message>

Note: by default, the message is set to "Update".

Under the hood, the program Git is used.


------------------------------------------------------------------


[gitinit.help]
Initialize a new Git repository then create a new connection
to the remote repository

Usage:
    backstage gitinit

Under the hood, the program Git is used.


------------------------------------------------------------------


[gitpush.help]
Send the commits from your local Git repository to the remote repository

Usage:
    backstage gitpush
    backstage gitpush <version_tag>

Under the hood, the program Git is used.


------------------------------------------------------------------


[init.help]
Initialize the Python project

Usage:
    backstage init

Under the hood, the package 'setupinit' is used.


------------------------------------------------------------------


[release.help]
Release a new version of this project

Usage:
    backstage release
    backstage release then <next_version>

Example:
    backstage release then 3.0.1
    backstage release then +maj

Under the hood, 'Git', 'buildver' and 'twine' are used.


------------------------------------------------------------------


[test.help]
Run tests

Usage:
    backstage test

Under the hood, the module 'unittest' is used.


------------------------------------------------------------------


[upload2pypi.help]
Upload the recently built distribution package to PyPI

Usage:
    backstage upload2pypi

Under the hood, the package 'twine' is used.