Skip to content

Commit

Permalink
Merge pull request #201 from epfl-lasa/release/v4.0.0
Browse files Browse the repository at this point in the history
Version 4.0.0 introduces some powerful new features
for using `state_representation` objects in real applications,
including the brand new `clproto` C++ serialization library
on the basis of Protobuf.

Many additional fixes and improvements have been made
across the modules, and some deprecated methods
have now been removed with this major version release.

This release also marks the repository being renamed to
`control-libraries` (formerly `control_libraries`). 

See the CHANGELOG and release notes for more details.
  • Loading branch information
eeberhard authored Sep 8, 2021
2 parents cfbc2eb + d1a492b commit dc89713
Show file tree
Hide file tree
Showing 114 changed files with 8,856 additions and 1,733 deletions.
5 changes: 5 additions & 0 deletions .github/actions/build-test-protocol/Dockerfile
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
FROM ghcr.io/epfl-lasa/control-libraries/development-dependencies:latest

# Copy and set the entrypoint commands to execute when the container starts
COPY entrypoint.sh /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]
5 changes: 5 additions & 0 deletions .github/actions/build-test-protocol/action.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
name: 'Build and Test Protocol'
description: 'Build the protobuf message libraries and run all unit tests'
runs:
using: 'docker'
image: 'Dockerfile'
23 changes: 23 additions & 0 deletions .github/actions/build-test-protocol/entrypoint.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
#!/bin/sh -l

echo ">>> Installing control libraries..."
bash /github/workspace/source/install.sh --auto --no-controllers --no-dynamical-systems --no-robot-model || exit 1
ldconfig

echo ">>> Building proto bindings..."
cd /github/workspace/protocol/protobuf && make all || exit 2

echo ">>> Configuring clproto_cpp cmake..."
cd /github/workspace/protocol/clproto_cpp && mkdir build && cd build \
&& cmake -DCMAKE_BUILD_TYPE=RELEASE -DBUILD_TESTING=ON .. \
|| (echo ">>> [ERROR] Configuration stage failed!" && exit 3) || exit $?

echo ">>> Building clproto_cpp..."
make all || (echo ">>> [ERROR] Build stage failed!" && exit 4) || exit $?
echo ">>> Build stage completed successfully!"

echo ">>> Running all test stages..."
CTEST_OUTPUT_ON_FAILURE=1 make test || (echo ">>> [ERROR] Test stage failed!" && exit 5) || exit $?
echo ">>> Test stages completed successfully!"

exit 0
2 changes: 1 addition & 1 deletion .github/actions/build-test-python/Dockerfile
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
FROM ghcr.io/epfl-lasa/control-libraries/development-dependencies:latest

# Copy and set the entrypoint commands to execute when the container starst
# Copy and set the entrypoint commands to execute when the container starts
COPY entrypoint.sh /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]
1 change: 1 addition & 0 deletions .github/actions/build-test-python/entrypoint.sh
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
#!/bin/sh -l

echo ">>> Installing control libraries..."
bash /github/workspace/source/install.sh --auto --no-controllers --no-dynamical-systems --no-robot-model || exit 1
ldconfig

Expand Down
2 changes: 1 addition & 1 deletion .github/actions/build-test/Dockerfile
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
FROM ghcr.io/epfl-lasa/control-libraries/development-dependencies:latest

# Copy and set the entrypoint commands to execute when the container starst
# Copy and set the entrypoint commands to execute when the container starts
COPY entrypoint.sh /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]
31 changes: 31 additions & 0 deletions .github/workflows/build-push.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
name: Build and Push

# Run workflow on pushes to main branch or by manual dispatch
on:
push:
branches:
- main
workflow_dispatch:

jobs:

build-publish-development-dependencies:
runs-on: ubuntu-latest
name: Build and publish development dependencies image
steps:
- name: Checkout Repository
uses: actions/checkout@v2

- name: Build image
run: |
docker build . --file ./Dockerfile.base --tag development-dependencies
- name: Login to GitHub Container Registry
run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin

- name: Push image
run: |
IMAGE_NAME=${{ github.repository }}/development-dependencies:latest
IMAGE_NAME=${IMAGE_NAME/_/-}
docker tag development-dependencies ghcr.io/${IMAGE_NAME}
docker push ghcr.io/${IMAGE_NAME}
12 changes: 12 additions & 0 deletions .github/workflows/build-test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -48,3 +48,15 @@ jobs:
# Load the repository build-test-python action
- name: Build and Test Python
uses: ./.github/actions/build-test-python

build-test-protocol:
needs: build-test-release
runs-on: ubuntu-latest
name: Protocol library test
steps:
# First check out the repository
- name: Checkout
uses: actions/checkout@v2
# Load the repository build-test-python action
- name: Build and Test Protocol
uses: ./.github/actions/build-test-protocol
47 changes: 47 additions & 0 deletions .github/workflows/generate-docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
name: Generate and Deploy Documentation
on:
push:
branches:
- main
- develop
release:
workflow_dispatch:

jobs:
deploy:
name: Generate and Deploy
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@master

- name: Generate docs
uses: mattnotmitt/doxygen-action@v1
with:
working-directory: 'doxygen'
doxyfile-path: 'doxygen.conf'

- name: Tag release version
if: ${{ github.event_name == 'release' }}
shell: bash
run: |
TAG="${GITHUB_REF#refs/heads/}"
TAG="${TAG/\//-}"
mkdir -p doxygen/docs/versions
sudo mv doxygen/docs/html doxygen/docs/versions/${TAG}
- name: Tag branch version
if: ${{ github.event_name == 'push' || github.event_name == 'workflow_dispatch' }}
shell: bash
run: |
BRANCH="${GITHUB_REF#refs/heads/}"
BRANCH="${BRANCH/\//-}"
mkdir -p doxygen/docs/versions
sudo mv doxygen/docs/html doxygen/docs/versions/${BRANCH}
- name: Deploy to documentation branch
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_branch: docs
publish_dir: ./doxygen/docs
keep_files: true
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -43,3 +43,6 @@ source/build

# clang-format
.clang-format

# protobuf generated bindings
protocol/protobuf/bindings/
96 changes: 87 additions & 9 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,98 @@
# CHANGELOG

Release Versions:
- [4.0.0](#400)
- [3.1.0](#310)
- [3.0.0](#300)
- [2.0.0](#200)
- [1.0.0](#100)

## 4.0.0

Version 4.0.0 introduces some powerful new features for using `state_representation` objects
in real applications, including the brand new `clproto` C++ serialization library on the basis of Protobuf.

Many additional fixes and improvements have been made across the modules, and some deprecated methods
have now been removed with this major version release.

This release also marks the repository being renamed to `control-libraries` (formerly `control_libraries`).

See the following notes for more details.

### Breaking changes

This release contains the following breaking changes:
- Rename repository to control-libraries
- Remove previously deprecated from_std_vector function (#186)
- Remove invalid multiplication operators for CartesianState and its derived classes (#195)

**Repository namespace**

The repository and all associated references have been renamed from `epfl-lasa/control_libraries` to
`epfl-lasa/control-libraries`. This is to better match the GitHub repository standard style and to match
the pattern in the container names. This breaking change will necessitate downstream users to update their
installation paths when cloning from GitHub.

**state_representation**

The following functions have been removed:
- `CartesianState::from_std_vector`
- `CartesianPose::from_std_vector`
- `Ellipsoid::from_std_vector`
- `JointState::from_std_vector`
- `JointPositions::from_std_vector`

The following multiplication operations are no longer permitted:
- `CartesianState *= CartesianPose | CartesianTwist | CartesianWrench`
- `CartesianPose *= CartesianTwist | CartesianWrench | CartesianState`
- `CartesianTwist *= CartesianPose | CartesianTwist | CartesianWrench | CartesianState`
- `CartesianTwist * CartesianPose | CartesianTwist | CartesianWrench | CartesianState`
- `CartesianWrench *= CartesianPose | CartesianTwist | CartesianWrench | CartesianState`
- `CartesianWrench * CartesianPose | CartesianTwist | CartesianWrench | CartesianState`

The permitted multiplication operations are:
- `CartesianState *= CartesianState`
- `CartesianState * CartesianPose | CartesianTwist | CartesianWrench | CartesianState`
- `CartesianPose *= CartesianPose`
- `CartesianPose * CartesianPose | CartesianTwist | CartesianWrench | CartesianState`

### Features

The biggest feature to come with 4.0.0 is the Protobuf schema for `state_representation` types and the
associated `clproto` C++ serialization library. See the documentation for more information.

Speaking of documentation, documentation is now generated and hosted for each release and for the main and develop
branches at:
[https://epfl-lasa.github.io/control-libraries](https://epfl-lasa.github.io/control-libraries)

Similarly, docker images for development and downstream use are now also built and hosted automatically.

The `state_representation` API has seen a number of smaller features to introduce new classes, methods and operators.

- Protobuf message protocol and C++ binding library `clproto` for serializing and deserializing control library objects
(#168, #175, #177, #179, #180, #190)
- Build and push development dependencies image in CI and related restructuring of Docker resources (#169)
- Add automatic documentation generation and deployment to GitHub Pages (#170, #199)
- Add set_data function declaration to all State objects (#163, #166)
- Add class JointAccelerations (#173)
- Methods for packing and unpacking multiple encoded state messages
into serialized message packets (#182)
- Add scalar division operator for CartesianState and its derived classes (#192)

### Fixes and improvements

- Correct an error in the `makefile` of the protobuf bindings and remove
the generated bindings from the repository, while providing installation scripts (#174)
- Fix clamp_state_variable function for CartesianState and JointState (#176, #191)
- Install tagged versions of osqp and osqpEigen (#184)
- Add missing integration constructor from JointAccelerations for JointVelocities (#185)
- Fix path to Dockerfile in demos (#197)

### Behind the scenes

- Refactor JointState tests and split them into separate test suites (#183, #187)
- Refactor CartesianState tests and split them into separate test suites (#188)

## 3.1.0

Version 3.1.0 contains a few improvements to the behaviour and usage
Expand All @@ -30,15 +117,6 @@ of the libraries.
**general**
- Use release configuration in install script (#155)

### Pending TODOs for the next release

- Revise `*=` and `*` operators in Cartesian types before the next release with
breaking changes (some are marked *deprecated*, and some are left as is, but
they should be deleted) (#156)
- Add the wrench computation in the `*` operator and `inverse` function (#134)
- Refactor and improve unittests for state_representation (especially JointState
and CartesianState)

## 3.0.0

Version 3.0.0 introduces Python bindings for the most commonly used
Expand Down
23 changes: 16 additions & 7 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@ This repository is still under development, and we welcome user engagement to
find bugs, resolve issues and add useful features.

Before contributing to this repository, please first discuss the change you wish to make
by using the repository [Discussions](https://github.com/epfl-lasa/control_libraries/discussions),
opening an [issue](https://github.com/epfl-lasa/control_libraries/issues),
by using the repository [Discussions](https://github.com/epfl-lasa/control-libraries/discussions),
opening an [issue](https://github.com/epfl-lasa/control-libraries/issues),
or by contacting the maintainers of this repository directly.


Expand Down Expand Up @@ -94,10 +94,19 @@ The `develop` branch is always considered to be a "release candidate" that conta
code. If, at release time, there are features on `develop` that are considered unfinished or broken,
they can be marked as `EXPERIMENTAL` to exclude them from compilation.

At the time of release, a release branch should be made from development which updates the project version number
in the [top-level CMakeLists](source/CMakeLists.txt) and finalises the [changelog](CHANGELOG.md).
A linear GitFlow strategy is used to merge this release branch into `main`, and then additionally squash and rebase
the release branch back into `develop`.
At the time of release, a release branch should be made from development. In the release branch,
the project version number should be updated in the following locations:
- The [top-level CMakeLists](./source/CMakeLists.txt)
- The [python bindings setup.py](./python/setup.py)
- The [clproto bindings CMakeLists](./protocol/clproto_cpp/CMakeLists.txt)
- The PROJECT_NUMBER in the [doxygen config](./doxygen/doxygen.conf)

In addition, the release branch should be used to finalize the [changelog](CHANGELOG.md), which includes
moving all content from the "Upcoming changes (in development)" header under a new header with the corresponding
release version.

Once the changes specific to the release have been approved, a linear GitFlow strategy is used to
merge this release branch into `main`, and then additionally squash and rebase the release branch back into `develop`.

View and join the full discussion surrounding release workflow and strategy here: \
https://github.com/epfl-lasa/control_libraries/discussions/77
https://github.com/epfl-lasa/control-libraries/discussions/77
Loading

0 comments on commit dc89713

Please sign in to comment.