[ros-users] best practices for ROS package repositories?

[Michael Quinlan]

Hi All,
  Most of this comes down to naming and documentation. A poorly named
and/or poorly documented package is rarely useful, even if the code
itself is extremely good. This will only get worse as the number of
packages increases, and as we all know one of the biggest hurdles to
code reuse is startup time. If it takes too long to
find/understand/use someones code then many developers end up
rewriting code simply out of annoyance. While I think the flexibility
and openness of the ROS repository system is great, and it goes a long
way to encouraging reuse, it could still do with some guidelines
(which are actually enforced).

I tend to agree with all the suggestions by Jürgen,Jack and Ken, but
I'd also add:

a) Each package should have keywords associated with it. For example
if I wanted to look at all the possible vision algorithms I could do
so easily, currently you have to search for various phrases such as
vision or image or camera etc to discover the complete list.

b) Similar to the sandbox discussion, we should have a way of not
listing 'lab specific' packages on the main packages page, maybe a
'Don't list' Tag in the manifest? I feel like many packages are
extremely related to the work of a given person/lab, and these are
starting to clutter the list (it's pretty easy to spot a few without
moving very far down the list). For example, I may write a nice
reusable SLAM package, but I also have x number of packages which are
mainly for running experiments and for my own personal use. These may
be interesting to someone if they want to see how I used the SLAM
package, but in general I can't see any real reason why others  need
them. In that case those other packages should not be on the main
list, rather they should be linked off the SLAM package documentation
(or found via a stack/repository search), that way people can easily
grab them if needed but most people can happily be unaware of them.

c) 'Browse software' should have a 'stacks' link as well as 'packages'
and 'repositories'

Michael

On Thu, Aug 19, 2010 at 11:35 AM, Ken Conley <kwc at willowgarage.com> wrote:
> Hi Jürgen, Jack,
>
> This discussion brings me back to when Morgan first launched
> sail-ros-pkg and came up with experimental, semistable, and broken as
> the classification system for packages :).
>
> This is a case where repository maintainers are going to have to tell
> WG what you want us to support. One of the things we like about ROS is
> that lets you exercise a lot of freedom in organizing your code, and
> it also has a low barrier to entry for distributing code. We'd rather
> not tamper with that by telling people how they have to organize their
> code and raising the barrier to having your code distributed.
>
> There are several different types of issues to address here:
>
>  1) versioning: which distribution release is a package intended for?
>  2) completeness: is a package a work in progress, or done?
>  3) value: how useful is a package?
>  4) uniqueness: how unique is a package in providing certain functionality
>
> Each of these issues has slightly different requirements.
>
> 1) versioning: we are attempting to address this by allowing people to
> release stacks in the same way that WG releases stacks. Stack releases
> are always against a particular ROS distribution release. We will need
> to update the wiki and rosbrowse to make this versioning more explicit
> in the documentation that you read.
>
> 2) completeness: This one is hard to completely address, though there
> are partial solutions:
>
>  * stack releases: a stack release usually comes as packages mature more.
>  * <review status>: Inside WG, we also use the <review> tag to
> indicate completeness (unreviewed->experimental->api reviewed->doc
> reviewed) once something has reached a stack-worthy stage. Right now
> this is fairly specific to WG process. One possibility is to come up
> with a new ontology of statuses that would allow outside people to
> contribute review statuses more effectively.
>  * 'sandbox': 'sandbox' is definitely easier for mass-marking packages
> as unfinished, but doesn't provide much of a path beyond that.
>
> 3) value: Jürgen's proposed some features. 2a is already implemented
> to some extent. If you go to the ROS wiki page for a package, the
> "Used by" is calculated against the ROS package universe (295 for
> rospy, woohoo!). It would be cool to be able to use this in the
> rosbrowse search somehow -- it's a bit like citation index. I'd argue
> that some of the other temporal features are actually artifacts of
> (1). If a stack is released against cturtle, but not diamondback, it
> will naturally decay. The question, I guess, is whether or not to do
> this for the stuff in between (packages that have not been released
> with a stack).
>
> 4) uniqueness: With respect the exploding number of packages, I think
> there is only a problem if there are competing packages. If there is
> only one package that implements an algorithm that you wish to use,
> then there is nothing to rate it against, and it's better that it
> exists and is indexed, than not.  So far, it seems that the community
> is doing a good job culling competing drivers (e.g. firewire,
> swissranger, etc...). Without naming names, is competing packages a
> major issue?
>
>
> At WG, we've chosen to do most of our development out in the open,
> from package birth to stack release. In some cases this has led to
> some frustration where people try to use stuff that we don't want them
> to (e.g. even after we delete the packages), but it also means that
> those packages are developed with more feedback. We've also had at
> least one case internally where a quick hack utility got discovered by
> someone else and turned into a real package. Indexing even the bad
> stuff has value for turning bad into good.
>
> My personal vision for diamondback and e-turtle is that the stack
> release system will become the main distribution vehicle for code. The
> stack release system will be used for more mature code, as well as
> code stamped in a working state. The existing, code repository search
> system will continue to be valuable for exploring the full ecosystem.
>
> Right now, if you have a PR2, you are pretty set for stable stuff
> (apt-get install ros-cturtle-pr2) and bleeding edge (apt-get install
> ros-cturtle-pr2all). I'm hoping that we take this one step further
> with the PR2 Beta Program where cool demo at one institution can be
> apt-get installed everywhere else.
>
> Extending this idea to other robots, you could "apt-get install
> ros-eturtle-nao" , or "apt-get install ros-eturtle-create" and
> immediately be up and running with all the mature stacks for your
> platform, and someone responsible for those platforms could also
> curate the bleeding edge stacks for that platform as well.
>
>  - Ken
>
>
> On Thu, Aug 19, 2010 at 1:36 AM, Jürgen Sturm
> <sturm at informatik.uni-freiburg.de> wrote:
>> Hi Jack, Ken,
>>
>> I was thinking about the same problem for the package list on ROS.org
>> and our ALUFR-ROS-PKG repository. I think that it is good practice to
>> place unfinished or only partially working packages in a sandbox
>> folder, and not to index them (or at least mark them as
>> "sandbox/unstable" on ROS.org.
>>
>> Regarding the sheer number of packages that will appear for ROS in the
>> next years, I think that a good solution would be to somehow compute
>> some automatically extracted features that help users to find/sort
>> packages more easily. May I propose the following features to be added
>> to the package list (and the package wiki page):
>>
>> 1. last commit date (or time since last commit)
>> 2a. number of other packages that depend on this package
>> 2b. latest commit date of dependent packages
>> 3a. number of packages that depend on this package from other institutions
>> 3b. latest commit date of dependent packages from other institutions
>>
>> This list is not complete, but this would help me to recognize how old
>> packages are, how well maintained, and how useful.
>>
>> Cheers
>> Juergen
>>
>>
>> On Tue, Aug 17, 2010 at 5:36 AM, Jack O'Quin <jack.oquin at gmail.com> wrote:
>>> On Mon, Aug 16, 2010 at 2:13 PM, Ken Conley <kwc at willowgarage.com> wrote:
>>>> Hi Jack,
>>>>
>>>> Right now, the only rule is that we will index whatever URL you give
>>>> us for your repo. Some repos use svn externals; in rare cases we index
>>>> multiple URLs.
>>>>
>>>> We're working on bringing up a better toolchain to support releases
>>>> and more structure to external repositories. If this toolchain works,
>>>> it means that you will be able to use the same tools that we use
>>>> internally here to manage the structure of our repositories in
>>>> conjunction with releases and documentation. If you'd like to be a
>>>> tester for this, let me know.
>>>>
>>>> There are two parts/phases to bringing up this toolchain:
>>>>
>>>> Phase 1: releases: supporting external releases of stacks into ROS
>>>> distribution. This allows them the same access to deb-building,
>>>> auto-generation of rosinstall files, etc...
>>>>
>>>> Phase 2:  documentation: right now we manually maintain the list of
>>>> repositories that we index for rosbrowse. After we're sure we have
>>>> phase 1 right, we transition rosdoc/rosbrowse to support rosinstall
>>>> files. This should kill two birds with one stone: the rosinstall file
>>>> that rosdoc/browse use could be the same rosinstall file you use for
>>>> people to install your repo, and could be the same rosinstall file
>>>> that our toolchain above generates.
>>>
>>> That sounds good. Thanks.
>>>
>>> I am glad to help with testing (although I won't want to reorganize
>>> our repo again until after the fall semester).
>>>
>>>> We try not to make blanket statements on how repositories have to be
>>>> organized. We've chosen to organize our repos the way we have because
>>>> we have 50+ researchers, engineers and interns working across very
>>>> different areas of development and at different levels. We have to
>>>> keep a careful balance of exploratory development and focused
>>>> engineering, and we're still tuning that balance. There are also
>>>> multiple organizations using GIT instead of SVN, and GIT has very,
>>>> very different usage patterns.
>>>
>>> Sounds like we should leave things mostly the same for this coming
>>> semester. With one URL for the repository it all needs to stay
>>> together.
>>>
>>> That's OK, we don't have that many developers, so we can release all
>>> the stacks in sync without much problem. I don't see any reason to
>>> define a separate URL for each stack at this point. Once phase 2 is
>>> available we can revisit the tree structure.
>>>
>>> Regards,
>>> --
>>>  joq
>>> _______________________________________________
>>> ros-users mailing list
>>> ros-users at code.ros.org
>>> https://code.ros.org/mailman/listinfo/ros-users
>>>
>> _______________________________________________
>> ros-users mailing list
>> ros-users at code.ros.org
>> https://code.ros.org/mailman/listinfo/ros-users
>>
> _______________________________________________
> ros-users mailing list
> ros-users at code.ros.org
> https://code.ros.org/mailman/listinfo/ros-users
>