[Ros-release] Best practices for hosting bloom GBP release repositories?

[Jack O'Quin]

On Sat, Mar 30, 2013 at 3:04 PM, William Woodall
<william at osrfoundation.org> wrote:
> On Sat, Mar 30, 2013 at 8:37 AM, Jack O'Quin <jack.oquin at gmail.com> wrote:
>>
>> I've finally managed to convert some packages to catkin and release
>> them via bloom. The catkin conversions took far too long, but they
>> seem to work, now. The bloom scripts work fine.
>>
> I'm sorry to hear that the catkinization took so long, I know you have been
> asking questions related to catkinization on answers.ros.org, so hopefully
> others who hit the same snags will find your Q/A's. Are there other concrete
> things we can do to improve this for others?

Yes, although that's a big discussion.

In my view, the first thing to work on is the organization of the
documentation. There is a lot of useful information on the wiki, but
it's not very user-oriented. Answers to specific questions are hard to
find. Some pages assume a much deeper understanding of CMake than a
lot of people have, including me. Other places assume an understanding
of the overall catkin design, which is quite complex and very
different from rosbuild.

For example, we had a question recently about installing files:

 http://answers.ros.org/question/59604/catkin-files-are-not-found-after-install-wrong-directories/

Many people coming from rosbuild are not expecting to write a bunch of
special-purpose code so other packages can use their API. The
knowledge of how to do that is scattered throughout the catkin
documentation. I'd like to see a topic page with everything you need
to know about installing files. It should explain the design; describe
the relevant CMake install() macro options (which are not very well
documented or easy to find); and provide a long list of recipes for
installing various objects: headers, shared libraries, messages, data
files, Python modules, Python scripts. They all work differently. That
is probably too much for a single page, but it could at least
introduce the subject and link to detailed pages for each type of
object.

Dependencies are another big topic needing an organized approach. What
goes in package.xml versus CMakeLists.txt? What is the difference
between a ROS dependency and a rosdep? What makes something a build,
run, or test dependency? Why are some things more than one? When do
they also need to appear in CMakeLists.txt? What about setup.py? What
types of objects need to appear in catkin_package(), and why? Most of
this information appears somewhere, but it's hard to find

Catkin never had a doc review for Groovy. I recommend holding one for
Hydro. I intend to spend some time making improvements, myself.

It does not help that most core components were converted while catkin
was still evolving. Many of their build files are confusing, not
following best practice. CMake tends to provide many solutions for a
single problem. I recommend doing code reviews on some representative
packages that cover most of the use cases, then listing them
explicitly as "good examples" in the documentation.

I could go on. We should open a separate thread on ros-sig-buildsystem.

>> So far, I host my GBP release repositories in the same github
>> organization that contains the corresponding source repo. I figure the
>> same group of people do development, maintenance and releases. But, I
>> suppose that's not necessarily true in general.
>>
>> As soon as its dependencies are available in Hydro, I will release a
>> catkinized camera1394, which belongs to the ros-drivers organization.
>> I don't see any other GBP repos in ros-drivers. Many ROS core packages
>> are released via the ros-gbp organization.
>>
>>  * What are the advantages of that approach?
>
>
> I think the reason we have done that historically, was because the
> organizations were already large, and having the release repositories in the
> sam organization would double the size, really cluttering things up.
>
> The side affect of this is that as a person who is keeping the build farm
> running, I don't have to know which organization a given repository is, I
> can guess at the url: github.com/ros-gbp/<repo>-release. If that doesn't
> hit, then I have to go to the rosdistro file and look up the location of the
> release repository.
>
>>
>>
>>  * What is the recommended hosting scheme for packages like mine?
>
>
> If you are releasing code into one of the ros-* organizations then you
> should probably put the release repository in ros-gbp, if you need
> permission just ask. Otherwise host the release repository in the same org
> as the upstream source or create your own -gbp org if things are getting
> cluttered.

Some other ros-drivers packages are already released via ros-gbp. But,
the main point of github organizations is collecting developers who
work on related components. Since ros-drivers are already separate, I
think I'll suggest on ros-sig-drivers that we create a parallel
ros-drivers-gbp organization with similar membership for doing our
releases.

--
 joq