Stable Release?

[marip8]

What is the plan for a release of tesseract with a stable API? Per this issue we agreed to follow semver which says that anything can change in 0.y.z. That's nice, but it's causing a lot of problems for me. I (and presumably others) can't stay on the master branch of all of these repositories all of the time, so breaking API in minor and patch changes makes it really hard to understand how to chain the tesseract, tesseract_planning, and tesseract_ros repositories together in a buildable workspace.

Here are a few examples I encountered recently:

• tesseract_planning 0.9.4 specifies trajopt 0.2.0, but does not build with version 0.2.5
• tesseract_planning 0.9.4 uses tesseract 0.8.x docker image in its CI build
• tesseract_planning 0.8.1 does not build with tesseract 0.8.7
• tesseract had a breaking API change in the IKFast kinematics constructor from 0.7.0 to 0.7.4

Technically this follows semver but it's becoming pretty painful in my applications that use tesseract. It seems like tesseract and tesseract_planning have matured enough for a 1.0.0 stable release, so I propose that we release that version and start tracking API breaking changes more thoroughly. I understand there will continue to be API breaking changes in the future, but we should address those by incrementing the major version. I don't think that technically has any stronger implications on the maintainers of tesseract to support these stable versions any more than we support the versions we have now (although it might pressure us to keep the API consistent for longer). It should just make it easier to understand how to use all of these repositories together

[Levi-Armstrong]

What if we create a tesseract_stable repository with three rosinstall files. This is similar to how boost handles this where they leverage submodules. We could set CI which builds each of these. This way we point people to here for stable version.

• tesseract.rosinstall -> includes tesseract, tesseract_planning and tesseract_qt
• tesseract_ros.rosinstall -> includes tesseract, tesseract_planning, tesseract_qt and tesseract_ros
• tesseract_ros2.rosinstall -> includes tesseract, tesseract_planning, tesseract_qt and tesseract_ros2

[dpiet]

We're exploring tesseract and would welcome a stable release option as well. Perhaps a release could also include a centralized changelog? Right now you have to dig into each module to determine what, if anything, has changed in a tagged version release.

[Levi-Armstrong]

@dpiet Are you wanting a single changelog for the repository?

[marip8]

What if we create a tesseract_stable repository with three rosinstall files. This is similar to how boost handles this where they leverage submodules. We could set CI which builds each of these. This way we point people to here for stable version.

That would be one solution, but I feel like that would be just one more repository that doesn't stay up to date. Is there a problem with making the next tesseract release 1.0.0 and then tracking changes per semver? I don't think releasing a "stable" release puts us under any obligation to stop making changes (breaking or otherwise). It just obligates us to track the different types of changes explicitly.

The repository of tesseract rosinstall files might be useful in indicating how the latest versions relate to each other, but it doesn't say how all versions of the repositories relate to one another in the case that you can't (or don't want to) be on the latest release of all the repos. It would be really nice if I could piece together these repositories together by just interpreting the version numbers. This gets difficult for tesseract-derived repos (planning, qt, ROS, etc.), especially for cases when the derived repos make major and minor changes that are independent of the tesseract version they are associated with. A naive solution would be to prefix the derived repos version with the major.minor version of tesseract that they are compatible with: for example tesseract_planning 1.2.4.25.12 is compatible with tesseract 1.2+ and is on version 4.25.12. This solution seems a bit hacky, and probably breaks down for the ROS repos which depend on specific versions of both tesseract and tesseract_planning (and tesseract_qt now?).

All this to say, IMO we should at least be tracking tesseract with a "stable" release where we explicitly capture major minor and patch changes, and we should also come up with an appropriate strategy for managing the versions of the dependent repositories in a similar way

[Levi-Armstrong]

That would be one solution, but I feel like that would be just one more repository that doesn't stay up to date. Is there a problem with making the next tesseract release 1.0.0 and then tracking changes per semver? I don't think releasing a "stable" release puts us under any obligation to stop making changes (breaking or otherwise). It just obligates us to track the different types of changes explicitly.

I am not opposed to creating a 1.0.0 release and tracking changes per semver, which is what I have been trying to do where I increment the minor with API breaking changes and the patch with backward compatible changes. I think the real issue is having an automated way to detect this because as you have pointed out I have done a patch increment when it should have been a minor increment.

[jdlangs]

It would be really nice if I could piece together these repositories together by just interpreting the version numbers

I don't see how this could be done without some sort of strategy of releasing everything with the same version (which your prefix proposal more-or-less is). But maybe that's not a bad thing? Do tesseract_planning and tesseract_qt really need to be considered fully separate of tesseract and versioned separately? Presumably you could use some relatively simple tooling that would sync releases across all tied-together repos if any one of them was updated.

Edit: And if the version moved to >= 1, the patch number could remain independent.

[dpiet]

@dpiet Are you wanting a single changelog for the repository?

@Levi-Armstrong Yes I think that would be helpful in quickly seeing what is included in the release. But it's also outside the scope of this original issue.

[Levi-Armstrong]

You can see a full list of changes if you go to the GitHub release.

[marip8]

I don't see how this could be done without some sort of strategy of releasing everything with the same version (which your prefix proposal more-or-less is). But maybe that's not a bad thing? Do tesseract_planning and tesseract_qt really need to be considered fully separate of tesseract and versioned separately?

That would be alright, but I think the problem would be that you would have to increment the major and minor versions of tesseract when breaking changes were introduced in the downstream repositories, which could result in a bunch of different tags attached to the same commit. The same problem exists for the downstream repos when API breaking changes are introduced to tesseract that don't affect them. It's not really great, but it could certainly work.

I'm not sure why the widgets are in a separate repository from tesseract, but the planning components were moved out because we knew there would a lot of future API-breaking development on them and we wanted to separate them from the more stable "core" components

Presumably you could use some relatively simple tooling that would sync releases across all tied-together repos if any one of them was updated.

I looked around a little bit for some Github actions for checking API and ABI stability, but I didn't find a great solution in my limited search. Definitely worth looking into in more detail

[jdlangs]

the problem would be that you would have to increment the major and minor versions of tesseract when breaking changes were introduced in the downstream repositories, which could result in a bunch of different tags attached to the same commit.

Indeed, but why is that a problem?

I would argue there's really just one project here (organized into multiple repositories/packages), and treating them as if they are standalone separate projects only invites confusion.

[marip8]

I don't think it's a problem, necessarily. If we go that route we just need to commit to being diligent about updating all the repositories to reflect the correct version whenever a major or minor change occurs. I could see that being a task that easily slips through the cracks. Maybe we could automate it with a CI script that creates tags on the other repositories when its own version changes.

[jdlangs]

Agreed, the syncing definitely can't be left as a manual process.

[Levi-Armstrong]

If the goal is to have them all have the same version then should we just merge everything back into the tesseract repository? It has always been the plan to merge them back together and presumably after the planned refactoring of tesseract_planning. The only reason tessseract_qt is separate is because tesseract and tesseract_planning are two separate repositories.

[Levi-Armstrong]

Indeed, but why is that a problem?

I would argue there's really just one project here (organized into multiple repositories/packages), and treating them as if they are standalone separate projects only invites confusion.

The idea of splitting up the initial repository was that we could make binary releases of tesseract which should not be changing significantly and then we would only need the source for tesseract_planning and tesseract_ros which was anticipated to change more frequently. If every time a break change is made in tesseract_planning the version of tesseract must be incremented then this defeats the logic for splitting things into different repositories.

I really don't see a good solution here other than merging everything into a single repository. The second, would be better documentation. I also do not think we could automate this through github because each repository would have to have the ability to trigger incrementing the tags of each other creating circular dependencies. I could create a script that a user could run on there pc to call catkin_generate_changelog and catkin_prepare_release --version X.Y.Z on each of the repositories doing this.

Another option might be for tesseract_planning and tesseract_ros is to set the tesseract package version in the find_package. Then it would be explicit what version it needs and the user can make sure they have that tag checked out.

[Levi-Armstrong]

It looks like I still have to touch all three repositories in some fashion when the minor version of one is changes so my plan is to keep the minor versions synced moving forward.