[Ros-release] rosdoc_lite branches and Hydro documentation

[Jack O'Quin]

On Sat, Jul 27, 2013 at 1:51 PM, Dirk Thomas <dthomas at osrfoundation.org>wrote:

> The branching policy of a ROS package as well as a pure Python package is
> determined by the maintainer.
> For ROS packages there are two common options:
>  * creating separate branches for each distro
>  * keeping a single master from where a release is made into all distros
>  * (or sometimes even a mix: separate branches for Fuerte and Groovy but
> Hydro uses Groovy since there are no changes between those two)
>

That mixture is the usual situation for most packages. Except for a few
core ROS packages that really do change for every distro, most ROS packages
can and do support multiple distros in the same source. For those packages,
I dislike the ${DISTRO}-devel branch naming convention, because it tends to
create more branches than necessary, and obscures continuity of
implementation.

Normal version control practice works fine for things like this.
Development happens in "master" or "trunk", releases are tagged, and other
branches are only created for applying fixes to old releases or for new
experimental code. Almost every package I currently maintain has a
"rosbuild" branch for Electric and Fuerte (maybe released to Groovy also),
and a "master" that has been converted to catkin and works with Groovy and
Hydro.

For ROS distro independent releases there is commonly only one master
> branch.
>
> rosdoc_lite is a mixture of both.
> It needs two different branches for Fuerte (old logic) and Groovy/Hydro
> (new logic).
> The buildfarm checks out the respective branch and uses rosdoc_lite from
> source (as far as I know).


Adding the Groovy branch to the Hydro doc.yaml is the right way for this.
> Just creating a Hydro branch for the sake of have that name creates
> unnecessary overhead.
>

I agree that adding a hydro-devel branch makes no sense. That's why I asked
about this in the first place.

Since the groovy-devel version will presumably be around for a long time,
I'd like to call it "master". Unless you object, I'll make "master" an
identical fork of "groovy-devel", create pull requests to update the many
references including jenkins_scripts, then delete or retire "groovy-devel".


> I am not sure why rosdoc_lite is at all released as a ROS Debian package.
> That decision backdates to the time where Eitan / Wim worked on these
> tools.
>

It is released as a Debian because users need to run it.

Ideally, it should be python-rosdoc-lite and not ros-hydro-rosdoc-lite. I
suppose the problem is that it depends on genmsg, which depends on catkin,
and both of them would have to become distro-independent, first.

Does that imply that no catkin package can be distro-independent?

With the EOL of Fuerte coming soon we might want to consider removing the
> ROS distro specific package, unlisting it from the distro files including
> doc.
>

It has no useful API documentation right now. That's unfortunate, since doc
packages should be self-documenting. I'll open an issue to write some.

We don't want to remove the release entries until we have a reasonable
alternative...


> We could than either release it as a ROS distro agnostic pure Python
> package and deploy that on the farm using puppet or just keep it as it is
> and checkout the repo on the farm.
>

It needs to be released, because users require it.

Pip install is OK up to a point, but we've all been bitten by packages like
this that did not get updated when the rest of the Ubuntu repository
changed. So, I favor building a pure python-rosdoc-lite Ubuntu package,
too. I guess I'll have to learn how to do that.

-- 
 joq
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ros.org/pipermail/ros-release/attachments/20130727/69c106a8/attachment-0009.html>