Understand and fix rever ("news" workflow)

[FilippoOggionni]

Background

@ggarrett13 originally set up the rever tool for both tudat and tudatpy. Rever is a tool to manage release versioning, based on the news workflow where each contributor maintains a changelog. An (unfinished) page on the tudat developer docs gives info and reference about this.

Latest updates

The news workflow has not been used by contributors until now. Following the last developer meeting, it was decided to start releasing versions of tudat and tudatpy in a sound manner. The rever tool could greatly help in this direction.

What has been done

I have tried using rever both on tudat and tudatpy, but after some debugging the tool still outputs errors. It seems that a version was released through rever.

Issues

1. The tool produces errors that I have not been able to solve
2. In general, despite the documentation, I have not been able to fully understand the functioning of rever and the news workflow

For both points, some help from @ggarrett13 would be greatly appreciated.

Note 1

If the issues are too difficult to be solved, we can also decide to release software versions manually (i.e., via Github and git tags), as I see no problem with that. However, if we manage to understand rever and get it to work, the project would be improved as keeping track of the software development over time (through the rever-generated changelog) would be easier.

Note 2

Until a decision is not made on this, no changelog nor guidelines on what to do when developing software will be released (see minutes on Slack from last tudat developer meeting).

[FilippoOggionni]

Output from rever (on tudatpy):

tudat-multidoc) foggionni@mac-foggionni tudatpy % rever 0.6.0       
<unknown>:1: DeprecationWarning: invalid escape sequence \s
Activity 'authors' has already been completed!
Activity 'changelog' has already been completed!
Activity 'push_tag' has already been completed!
Activity 'tag' has already been completed!
Activity 'version_bump' has already been completed!
activity-start:forge:starting activity forge
Switched to branch 'master'
Your branch is up to date with 'origin/master'.
From https://github.com/FilippoOggionni/tudatpy-feedstock
 * branch            master     -> FETCH_HEAD
Already up to date.
From https://github.com/tudat-team/tudatpy-feedstock
 * branch            master     -> FETCH_HEAD
Already up to date.
fatal: A branch named '0.6.0' already exists.
activity-error:forge:activity failed with exception:
Traceback (most recent call last):
  File "/Users/foggionni/opt/miniconda3/envs/tudat-multidoc/lib/python3.8/site-packages/rever/activity.xsh", line 83, in __call__
    self.func(*args, **kwargs)
  File "/Users/foggionni/opt/miniconda3/envs/tudat-multidoc/lib/python3.8/site-packages/rever/activities/forge.xsh", line 248, in _func
    git checkout -b $VERSION master or git checkout $VERSION
  File "/Users/foggionni/opt/miniconda3/envs/tudat-multidoc/lib/python3.8/site-packages/xonsh/built_ins.py", line 202, in subproc_captured_hiddenobject
    return xonsh.procs.specs.run_subproc(cmds, captured="hiddenobject", envs=envs)
  File "/Users/foggionni/opt/miniconda3/envs/tudat-multidoc/lib/python3.8/site-packages/xonsh/procs/__amalgam__.py", line 3585, in run_subproc
    command.end()
  File "/Users/foggionni/opt/miniconda3/envs/tudat-multidoc/lib/python3.8/site-packages/xonsh/procs/__amalgam__.py", line 928, in end
    self._end(tee_output=tee_output)
  File "/Users/foggionni/opt/miniconda3/envs/tudat-multidoc/lib/python3.8/site-packages/xonsh/procs/__amalgam__.py", line 947, in _end
    self._raise_subproc_error()
  File "/Users/foggionni/opt/miniconda3/envs/tudat-multidoc/lib/python3.8/site-packages/xonsh/procs/__amalgam__.py", line 1069, in _raise_subproc_error
    raise subprocess.CalledProcessError(rtn, spec.args, output=self.output)
subprocess.CalledProcessError: Command '['git', 'checkout', '-b', '0.6.0', 'master']' returned non-zero exit status 128.
rewinding to 340c22a885f98236bd379b46d99c89e81b6c7df6

[geoffreygarrett]

HI @FilippoOggionni, I've encountered this because and usually it means (in this case) the command rever 0.6.0 has already been run resulting in what you referred to here?

I usually got around this by deleting the release/tag, or bumping the version again (not a neat solution). Regarding your issues above and the error encountered, I'll provide further clarification in combination with (an attempt at) a rever GitHub workflow which we use through /rever <version> on any comment in an issue via GitHub. (i.e. just like this invoking the action /rever 0.6.4)

[geoffreygarrett]

Still forming a solution to this such that tudat and tudatpy can release simultaneously. Managed to get the rerendering automated via GitHub workflows, a step in the right direction.

[geoffreygarrett]

Currently fixing the email addresses in tudats commit history so that the authors feature of rever works. Many commits had [email protected] for multiple users, and only one person can map to an email. Lot's of fun.

[geoffreygarrett]

Anonymous emails have been resolved, git history has been modified with some interesting by products:

This branch is 3744 commits ahead of Tudat:master.