[GRASS5] Suggested color function names

GRASS GIS GRASS GIS developer
1

Hi,

Hamish added a red, green, blue, alpha color structure to gis.h.

I'd like to add the following to gis.h as well:

/* RGBA_Color set values */
#define RGBA_COLOR_SET 1
#define RGBA_COLOR_UNSET 0
#define RGBA_COLOR_NONE -1

I also think it would be apropos to add some more functions that deal with
this structure instead of red, green, and blue integers. New functions means
new names. My current best idea is adding RGBA to the existing analogous
names.

We currently have

int G_str_to_color (str * name, int * red, int * green, int * blue);
int R_RGB_color(unsigned char,unsigned char,unsigned char);
int R_reset_color(unsigned char,unsigned char,unsigned char,int);
int R_reset_colors(int,int,unsigned char *,unsigned char *,unsigned char *);

How are these suggested names for new "functions":

int G_str_to_RGBA_color (str * name, RGBA_Color * color);
int R_RGBA_color(RGBA_Color * color);
int R_reset_RGBA_color(RGBA_Color * color, int);
int R_reset_colors(int,int,RGBA_Color ** colors);

The R_ functions would just use the existing protocol (no alpha support).

--Cedric

2

Cedric Shock wrote:

Hamish added a red, green, blue, alpha color structure to gis.h.

I'd like to add the following to gis.h as well:

/* RGBA_Color set values */
#define RGBA_COLOR_SET 1
#define RGBA_COLOR_UNSET 0
#define RGBA_COLOR_NONE -1

I also think it would be apropos to add some more functions that deal with
this structure instead of red, green, and blue integers. New functions means
new names. My current best idea is adding RGBA to the existing analogous
names.

We currently have

int G_str_to_color (str * name, int * red, int * green, int * blue);
int R_RGB_color(unsigned char,unsigned char,unsigned char);
int R_reset_color(unsigned char,unsigned char,unsigned char,int);
int R_reset_colors(int,int,unsigned char *,unsigned char *,unsigned char *);

How are these suggested names for new "functions":

int G_str_to_RGBA_color (str * name, RGBA_Color * color);
int R_RGBA_color(RGBA_Color * color);
int R_reset_RGBA_color(RGBA_Color * color, int);
int R_reset_colors(int,int,RGBA_Color ** colors);

The R_ functions would just use the existing protocol (no alpha support).

Alpha support in the current display architecture isn't going to
happen (I reverted the last attempt to add it, and will do likewise in
future). The core X API doesn't support it, and hacking it in is
grossly inefficient (read-modify-write cycles aren't practical on a
remote display).

Developers' time would be better spent replacing the modules which are
tied to the current architecture so that it can be discarded in favour
of a from-scratch replacement.

I'm referring to anything which uses R_get_location_with_*, primarily
v.digit and i.points.

--
Glynn Clements <glynn@gclements.plus.com>

3

Glynn,

This has little to do with alpha support in the displays. It has to do with
having a structure for colors. Hamish added one called RGBA_Color to gis.h.
These are just small changes to accommodate the color structure based on the
assumption that a color structure is a good idea. I'll take what you're
saying to mean that you don't like the name RGBA_Color for this structure or
the use of the letters RGBA in function names. If you have a better name
suggestion that won't lead to confusion over the existence of alpha in
displays please share it with us.

Thanks,

--Cedric

Alpha support in the current display architecture isn't going to
happen (I reverted the last attempt to add it, and will do likewise in
future). The core X API doesn't support it, and hacking it in is
grossly inefficient (read-modify-write cycles aren't practical on a
remote display).

Developers' time would be better spent replacing the modules which are
tied to the current architecture so that it can be discarded in favour
of a from-scratch replacement.

I'm referring to anything which uses R_get_location_with_*, primarily
v.digit and i.points.

4

> Alpha support in the current display architecture isn't going to
> happen (I reverted the last attempt to add it, and will do likewise
> in future). The core X API doesn't support it, and hacking it in is
> grossly inefficient (read-modify-write cycles aren't practical on a
> remote display).
>
> Developers' time would be better spent replacing the modules which
> are tied to the current architecture so that it can be discarded in
> favour of a from-scratch replacement.
>
> I'm referring to anything which uses R_get_location_with_*,
> primarily v.digit and i.points.

This has little to do with alpha support in the displays. It has to
do with having a structure for colors. Hamish added one called
RGBA_Color to gis.h. These are just small changes to accommodate the
color structure based on the assumption that a color structure is a
good idea. I'll take what you're saying to mean that you don't like
the name RGBA_Color for this structure or the use of the letters RGBA
in function names. If you have a better name suggestion that won't
lead to confusion over the existence of alpha in displays please
share it with us.

gis.h has nothing to do with display drivers or raster graphics
limitations, the RGBA_Color type is just for passing stuff around
regardless of GUI a, GUI b, GUI c, or none. Having alpha in there might
be useful for a future GUI "d" or simply if for some reason you want to
have a GRASSRGB and ALPHA columns in a vector attribute table and
push them around in your module. I don't really know for what it will
be used but I don't want it to be a limiting factor in the future
either. My hope is that the "from-scratch replacement", when it happens,
can use it right way without modification or a dupe version of almost
the same thing, without compromise.

Plus we can put a "support for 32-bit color" bullet on the box now. :slight_smile:

I can see the point that is that it is perhaps misleading to future
coders to start (at least tacitly) adding R_(r,g,b,a) fns or have a
system which is made up of even more patchwork of many differnt ideas.

Hamish

5

Cedric Shock wrote:

This has little to do with alpha support in the displays. It has to do with
having a structure for colors. Hamish added one called RGBA_Color to gis.h.
These are just small changes to accommodate the color structure based on the
assumption that a color structure is a good idea. I'll take what you're
saying to mean that you don't like the name RGBA_Color for this structure or
the use of the letters RGBA in function names. If you have a better name
suggestion that won't lead to confusion over the existence of alpha in
displays please share it with us.

I took the proposal of:

  int R_RGBA_color(RGBA_Color * color);
  int R_reset_RGBA_color(RGBA_Color * color, int);
  int R_reset_colors(int,int,RGBA_Color ** colors);

as implying that the alpha component would be used.

If that isn't the intention, I would change RGBA->RGB in the first two
function names. Also, add:

  typedef RGBA_Color RGB_Color;

and use RGB_Color for functions which ignore the alpha component.

Also, in the case of R_reset_colors(), you would need to either extend
the protocol to support interleaved data, or unpack the colours into
separate R/G/B arrays first.

In general, I'm against extending the protocol, or otherwise
attempting to enhance the existing display architecture. I want to
kill it off ASAP, and any enhancements will only make the task of
adding a backward compatibility layer to the new architecture harder.

BTW, I suggest removing the "set" field from the structure. Without
that field, the structure fits into 32 bits, and I suspect that most
functions would ignore that field anyhow.

In specific cases where you actually need a "set" field, you can use
a separate type, e.g.:

struct XRGBA_Color
{
  int set;
  RGBA_Color color;
}

Finally, I should mention that one of the reasons I'm against attempts
to "hack" alpha support into the architecture is that, so far as
possible, I would like the new architecture to support both video and
hardcopy output. And video-style alpha "blending" cannot be
implemented on hardcopy devices which typically only have one bit per
component. You can get a similar effect using halftones and
dither-masks, but the task is more complex than with video, and the
API needs to allow for that.

--
Glynn Clements <glynn@gclements.plus.com>

6

On Sat, Apr 22, 2006 at 01:00:01PM +0100, Glynn Clements wrote:

Cedric Shock wrote:

> Hamish added a red, green, blue, alpha color structure to gis.h.
>
> I'd like to add the following to gis.h as well:
>
> /* RGBA_Color set values */
> #define RGBA_COLOR_SET 1
> #define RGBA_COLOR_UNSET 0
> #define RGBA_COLOR_NONE -1
>
> I also think it would be apropos to add some more functions that deal with
> this structure instead of red, green, and blue integers. New functions means
> new names. My current best idea is adding RGBA to the existing analogous
> names.
>
> We currently have
>
> int G_str_to_color (str * name, int * red, int * green, int * blue);
> int R_RGB_color(unsigned char,unsigned char,unsigned char);
> int R_reset_color(unsigned char,unsigned char,unsigned char,int);
> int R_reset_colors(int,int,unsigned char *,unsigned char *,unsigned char *);
>
> How are these suggested names for new "functions":
>
> int G_str_to_RGBA_color (str * name, RGBA_Color * color);
> int R_RGBA_color(RGBA_Color * color);
> int R_reset_RGBA_color(RGBA_Color * color, int);
> int R_reset_colors(int,int,RGBA_Color ** colors);
>
> The R_ functions would just use the existing protocol (no alpha support).

Alpha support in the current display architecture isn't going to
happen (I reverted the last attempt to add it, and will do likewise in
future).

... this is why I really suggest to get interested in a project
steering committee [1], [2].

Instead of recursively reverted changes of other developers,
we should come up with a design discussion and then *vote* on it.
At least for such crucidal pieces of the code I would like to
see less anarchy and a more formal approach. This will render
development more transparent to everybody. The scope cannot be to
have two display management systems in parallel, one without
and one with alpha support.

Existing steering committees, to get inspired from:
Mapserver: http://mapserver.gis.umn.edu/development/rfc/ms-rfc-1
GDAL: http://www.gdal.org/rfc1_pmc.html
Mapbender: http://www.mapbender.org/index.php/Mapbender_PSC
...

Please think about it!

Thanks

Markus

[1] http://www.grass.itc.it/pipermail/grass5/2006-February/021178.html
[2] http://grass.itc.it/pipermail/grass5/2006-April/022185.html

7

Also, add:

  typedef RGBA_Color RGB_Color;

and use RGB_Color for functions which ignore the alpha component.

A good idea, but in include/ we already have

devlib.h:int RGB_color(unsigned char, unsigned char, unsigned char);
devlib.h:int Set_RGB_color(unsigned char,unsigned char,unsigned char);

(afaict devlib.h is not used by anything. unneeded copy from GRASS 5??)

graphics.h:#define RGB_COLOR 6
graphics.h:#define RGB_COLORS 52

I think it is confusing to have both RGB_Color and RGB_COLOR around.

also display/d.vect/plot.h has a rgb_color struct, but that is easy to
change to use RGBA_Color (or similar), or remove lookup table & set in
the main libs? (here d.vect random color defaults, purposefully
non-primary colors)

Hamish

8

BTW, I suggest removing the "set" field from the structure. Without
that field, the structure fits into 32 bits, and I suspect that most
functions would ignore that field anyhow.

In specific cases where you actually need a "set" field, you can use
a separate type, e.g.:

struct XRGBA_Color
{
  int set;
  RGBA_Color color;
}

I could live without set,unset, but how to do you pass a color of "none"
with just,

typedef struct
{
    unsigned char r, g, b, a; /* red, green, blue, and alpha */
} RGBA_Color ;

???

currently I have:

    ret = G_str_to_color(fill_color_str, &fill_color->r, &fill_color->g, &fill_color->b);
    if (ret == 1) {
  fill_color->a = 1; /* alpha channel is not used by the display drivers */
  fill_color->set = 1;
    }
    else if (ret == 2)
  fill_color->set = -1; /* "none" */
    else {
  G_warning(_("[%s]: No such color"), fill_color_str);
  return(-1);
    }

Note 1) G_str_to_color() returns R,G,B as int, causing a warning;
  Cedric's proposed G_str_to_RGBA_color() would fix that.
Note 2) "->set=RGBA_COLOR_SET;" if we add those (I think we should)

and I suspect that most functions would ignore that field anyhow.

That is just a matter of discipline. Currently we have 100% compliance :slight_smile:
If we do keep .set, the lib functions should definitely use it, even if
modules' caller fns ignore it.

Hamish

9

Hamish wrote:

> Also, add:
>
> typedef RGBA_Color RGB_Color;
>
> and use RGB_Color for functions which ignore the alpha component.

A good idea, but in include/ we already have

devlib.h:int RGB_color(unsigned char, unsigned char, unsigned char);
devlib.h:int Set_RGB_color(unsigned char,unsigned char,unsigned char);

(afaict devlib.h is not used by anything. unneeded copy from GRASS 5??)

Probably.

graphics.h:#define RGB_COLOR 6
graphics.h:#define RGB_COLORS 52

I think it is confusing to have both RGB_Color and RGB_COLOR around.

Don't worry about graphics.h; it's only used internally within the
display architecture (lib/raster and display/drivers/lib).

--
Glynn Clements <glynn@gclements.plus.com>

10

Hamish wrote:

> BTW, I suggest removing the "set" field from the structure. Without
> that field, the structure fits into 32 bits, and I suspect that most
> functions would ignore that field anyhow.
>
> In specific cases where you actually need a "set" field, you can use
> a separate type, e.g.:
>
> struct XRGBA_Color
> {
> int set;
> RGBA_Color color;
> }

I could live without set,unset, but how to do you pass a color of "none"
with just,

typedef struct
{
    unsigned char r, g, b, a; /* red, green, blue, and alpha */
} RGBA_Color ;

???

In what context does a colour of "none" make sense?

If you have a particular situation where you need additional
information other than just a colour, then create your own type for
that purpose.

There's no reason why everything which deals with colours needs to
carry that field around because something which uses colours needs it.

--
Glynn Clements <glynn@gclements.plus.com>

11

Markus Neteler wrote:

> Alpha support in the current display architecture isn't going to
> happen (I reverted the last attempt to add it, and will do likewise in
> future).

... this is why I really suggest to get interested in a project
steering committee [1], [2].

Instead of recursively reverted changes of other developers,
we should come up with a design discussion and then *vote* on it.

Who gets to vote? Anyone who wants to, only people who contribute
code, only people who will be affected by the decision, ...?

E.g. with a display architecture, the risk is that "application"
developers would vote for the ultimate graphics API which includes
everything provided by both OpenGL and PostScript and then some
extras, which consequently never gets implemented.

At least for such crucidal pieces of the code I would like to
see less anarchy and a more formal approach.

I'd certainly agree with the "less anarchy" part, although I'm not
sure that a "committee" is the answer. The mailing list is a perfectly
suitable forum; people just need to use it (the first thing anyone
heard about the alpha "enhancement" was a message informing everyone
that it had been committed).

A simpler solution would be to have defined maintainers for specific
sections of the code base. Developers would be expected to discuss any
non-trivial changes to another developer's section beforehand.
Maintainers would have more liberty to act within their own section,
but would still be expected to discuss more substantial changes,
particularly if the changes would be "visible" to users or other
developers (as opposed to purely internal changes such as refactoring
or optimisation).

This will render
development more transparent to everybody. The scope cannot be to
have two display management systems in parallel, one without
and one with alpha support.

We already have both the historical display architecture and ps.map.
Also, while gis.m is based on the historical display architecture, the
end result is sufficiently different to effectively be a third
architecture.

--
Glynn Clements <glynn@gclements.plus.com>

12

In what context does a colour of "none" make sense?

If you have a particular situation where you need additional
information other than just a colour, then create your own type for
that purpose.

Many of the display modules use a color of "none" to switch off the
drawing of some feature.

e.g. d.barscale background color.
e.g. d.vect fill or outline color. (vector area or symbol)
e.g. d.rast.arrow grid color.

Typically in a d.* module the color is taken from the command line:
    color either a standard GRASS color, R:G:B triplet, or "none"
           default: white

which is then parsed and the result passed on to an external draw fn:
   do_plot(, color);

If this was only used sparsely I can see the point of keeping RGBA_Color
compact and simple, but in practical use we'd use it all the time, and
you'd either have to define a new struct 50% of the time; change a large
number of function calls to add a really_draw_it flag; or start adding
the really_draw_it flag as a global variable. A "none" flag (aka draw
nothing/be transparent) in the color struct makes defining this
situation much more elegant- nan:nan:nan. Also it's a lot clearer to the
casual code reader seeing color.set=RGBA_COLOR_NONE; versus color.a=0;,
and I don't like conceptually mixing boolean tests with full fledged
int/char variables. [ if(color.a) draw_it(); ]

There's no reason why everything which deals with colours needs to
carry that field around because something which uses colours needs it.

What future plans do you have for widespead use of the RGBA_Color struct
which would make the above a corner case?

I can see the point about making it fit into 32 bytes etc if it is
destined for core use in the heart of the graphics engine*, but for the
current use I think the extra bloat justifies itself well.

[*] in that case make RGB_Color {r,g,b} and keep RGBA_Color as is, or
something along those lines.

Hamish

13

Hamish wrote:

> In what context does a colour of "none" make sense?
>
> If you have a particular situation where you need additional
> information other than just a colour, then create your own type for
> that purpose.

Many of the display modules use a color of "none" to switch off the
drawing of some feature.

e.g. d.barscale background color.
e.g. d.vect fill or outline color. (vector area or symbol)
e.g. d.rast.arrow grid color.

Typically in a d.* module the color is taken from the command line:
    color either a standard GRASS color, R:G:B triplet, or "none"
           default: white

which is then parsed and the result passed on to an external draw fn:
   do_plot(, color);

If this was only used sparsely I can see the point of keeping RGBA_Color
compact and simple, but in practical use we'd use it all the time, and
you'd either have to define a new struct 50% of the time; change a large
number of function calls to add a really_draw_it flag; or start adding
the really_draw_it flag as a global variable. A "none" flag (aka draw
nothing/be transparent) in the color struct makes defining this
situation much more elegant- nan:nan:nan. Also it's a lot clearer to the
casual code reader seeing color.set=RGBA_COLOR_NONE; versus color.a=0;,
and I don't like conceptually mixing boolean tests with full fledged
int/char variables. [ if(color.a) draw_it(); ]

In the case where "none" means "completely transparent" (i.e. not
drawn), I would suggest using the alpha component.

To me, a "set" field implies "the data in this structure is/isn't
valid" (i.e. "undefined"). If a function fills in caller-provided
structures, the field being zero means "I haven't filled this in",
while an input having the field set zero means "ignore this value"
(e.g. leave the previous setting unchanged).

If you're concerned about code clarity, using "if (color.a > 0)" may
be clearer. Or even making the display (D_*) functions perform this
optimisation internally (the application always calls the "draw"
function, but the library would skip drawing if the current colour is
transparent).

Alternatively, provide R/G/B/A and R/G/B/Set types, both 32 bits.

> There's no reason why everything which deals with colours needs to
> carry that field around because something which uses colours needs it.

What future plans do you have for widespead use of the RGBA_Color struct
which would make the above a corner case?

I can see the point about making it fit into 32 bytes etc if it is
destined for core use in the heart of the graphics engine*, but for the
current use I think the extra bloat justifies itself well.

Well, the more it's used, the more it makes sense for it to fit into a
32-bit word.

Lots of graphic APIs have RGB/RGBA colour structures, and most of them
don't have a "set" field.

--
Glynn Clements <glynn@gclements.plus.com>

14

Glynn Clements wrote:

Markus Neteler wrote:

Instead of recursively reverted changes of other developers,
we should come up with a design discussion and then *vote* on it.

Who gets to vote? Anyone who wants to, only people who contribute
code, only people who will be affected by the decision, ...?

Glynn,

I will respond based on how the MapServer or GDAL/OGR PSC operate.
There is certainly latitude for the GRASS community to define a PSC
that operates slightly differently.

Only the members of the PSC would get to vote. However, the
discussion and voting would normally occur on the public project
mailing list and anyone can express an opinion.

E.g. with a display architecture, the risk is that "application"
developers would vote for the ultimate graphics API which includes
everything provided by both OpenGL and PostScript and then some
extras, which consequently never gets implemented.

Normally the practice is that someone interested in implementing
a feature must prepare a proposal. This would be then discussed,
and potentially revised by the original proposer based on feedback
before a formal vote.

The GDAL and MapServer (and Apache) practice is that anyone who
votes +1 (ie. supporting the proposal) is also agreeing to help
with implementation if needed. But for the most part the original
proposer is responsible for implementing what they have proposed.
This highly motivates proposers to only propose what they are
prepared to implement.

At least for such crucidal pieces of the code I would like to see less anarchy and a more formal approach.

I'd certainly agree with the "less anarchy" part, although I'm not
sure that a "committee" is the answer. The mailing list is a perfectly
suitable forum; people just need to use it (the first thing anyone
heard about the alpha "enhancement" was a message informing everyone
that it had been committed).

Note that PSC committee discussions would be occuring on the public
mailing list. The PSC primarily provides a formal way of deciding
whether to adopt a proposal when it is unclear. The proposal
process is also very helpful in preventing the sort of surprise you
seem to have run into.

A simpler solution would be to have defined maintainers for specific
sections of the code base. Developers would be expected to discuss any
non-trivial changes to another developer's section beforehand. Maintainers would have more liberty to act within their own section,
but would still be expected to discuss more substantial changes,
particularly if the changes would be "visible" to users or other
developers (as opposed to purely internal changes such as refactoring
or optimisation).

This is essentially the process taken by the GeoTools project. They
have the GeoTools code base clearly broken into something like 10
modules, and each module has a module maintainer that is responsible
for their module, and relatively free to make internal changes as
desired.

I do think having module maintainers is a good idea if you have some
sort of logical way of segmenting the code, end have folks willing
to take on the responsibility for sections. But I think that having
public discussions of anything that could affect users or other modules
is important.

I would like to stress that a PSC based process is used by many successful
community projects. It is part of the Apache process for all Apache
projects. It is already used by GeoTools and MapServer quite successfully.
And with project specific variations it will be used for other OSGeo projects.
This is not a radical idea. It is a "best practice" for open source projects.

On a more meta level, I feel the GRASS community is not going out of it's
way to support Markus as he tries to bring GRASS into OSGeo. He needs
senior members of the GRASS community to get involved, and support this
migration work. That means working on a PSC charter, following the
"incubation process", helping with code copyright review, and participating
in other OSGeo activities.

The GRASS community has a lot of offer OSGeo and I hope OSGeo has a lot to
offer the GRASS community. You can tailor GRASS's involvement and also
contribute to the overall direction of the foundation. Already the GRASS
community feedback on the risk of relicensing has been taken very seriously
and contributed to us dropping the idea of contributor agreements.

PS. Sorry for missing Glynn's question about PSC voting on the first pass.
I have been skipping all the "suggested color function names" emails assuming
they were related to some esoteric detail of little interest to me. I have
taken the liberty of retitling this email.

Best regards,
--
---------------------------------------+--------------------------------------
I set the clouds in motion - turn up | Frank Warmerdam, warmerdam@pobox.com
light and sound - activate the windows | http://pobox.com/~warmerdam
and watch the world go round - Rush | President OSGF, http://osgeo.org

15

Frank, Markus,

if people on this list do not follow osgeo activities, it hard to understand from emails that Markus posted
what is needed for GRASS project incubation, setting up PSC, etc. So I am not surprised at all by Glynn's questions,
I had similar ones. So Markus, if you could let us know what needs to be done - step 1.2.3,
maybe we will get it moving. We have nominations for the PSC but nobody said what is next step - who votes
to set it up etc.
Frank, thank you for your explanation - this helps a lot - now we need to know what is the next step after nominations.
And BTW, as I have already expressed to Markus, we should really keep the management structures and procedures
to minimum (there already was a GRASS steering committee, GRASS interagency committe, GRASS foundation
and soon everybody is sitting in meetings and nobody has time for development and you also lose the freespirit
of open source development), so I am with Glynn on this, but
a minimal steering committee is really needed for reasons well explained by Frank,

Helena

Frank Warmerdam wrote:

Glynn Clements wrote:

Markus Neteler wrote:

Instead of recursively reverted changes of other developers,
we should come up with a design discussion and then *vote* on it.

Who gets to vote? Anyone who wants to, only people who contribute
code, only people who will be affected by the decision, ...?

Glynn,

I will respond based on how the MapServer or GDAL/OGR PSC operate.
There is certainly latitude for the GRASS community to define a PSC
that operates slightly differently.

Only the members of the PSC would get to vote. However, the
discussion and voting would normally occur on the public project
mailing list and anyone can express an opinion.

E.g. with a display architecture, the risk is that "application"
developers would vote for the ultimate graphics API which includes
everything provided by both OpenGL and PostScript and then some
extras, which consequently never gets implemented.

Normally the practice is that someone interested in implementing
a feature must prepare a proposal. This would be then discussed,
and potentially revised by the original proposer based on feedback
before a formal vote.

The GDAL and MapServer (and Apache) practice is that anyone who
votes +1 (ie. supporting the proposal) is also agreeing to help
with implementation if needed. But for the most part the original
proposer is responsible for implementing what they have proposed.
This highly motivates proposers to only propose what they are
prepared to implement.

At least for such crucidal pieces of the code I would like to see less anarchy and a more formal approach.

I'd certainly agree with the "less anarchy" part, although I'm not
sure that a "committee" is the answer. The mailing list is a perfectly
suitable forum; people just need to use it (the first thing anyone
heard about the alpha "enhancement" was a message informing everyone
that it had been committed).

Note that PSC committee discussions would be occuring on the public
mailing list. The PSC primarily provides a formal way of deciding
whether to adopt a proposal when it is unclear. The proposal
process is also very helpful in preventing the sort of surprise you
seem to have run into.

A simpler solution would be to have defined maintainers for specific
sections of the code base. Developers would be expected to discuss any
non-trivial changes to another developer's section beforehand. Maintainers would have more liberty to act within their own section,
but would still be expected to discuss more substantial changes,
particularly if the changes would be "visible" to users or other
developers (as opposed to purely internal changes such as refactoring
or optimisation).

This is essentially the process taken by the GeoTools project. They
have the GeoTools code base clearly broken into something like 10
modules, and each module has a module maintainer that is responsible
for their module, and relatively free to make internal changes as
desired.

I do think having module maintainers is a good idea if you have some
sort of logical way of segmenting the code, end have folks willing
to take on the responsibility for sections. But I think that having
public discussions of anything that could affect users or other modules
is important.

I would like to stress that a PSC based process is used by many successful
community projects. It is part of the Apache process for all Apache
projects. It is already used by GeoTools and MapServer quite successfully.
And with project specific variations it will be used for other OSGeo projects.
This is not a radical idea. It is a "best practice" for open source projects.

On a more meta level, I feel the GRASS community is not going out of it's
way to support Markus as he tries to bring GRASS into OSGeo. He needs
senior members of the GRASS community to get involved, and support this
migration work. That means working on a PSC charter, following the
"incubation process", helping with code copyright review, and participating
in other OSGeo activities.

The GRASS community has a lot of offer OSGeo and I hope OSGeo has a lot to
offer the GRASS community. You can tailor GRASS's involvement and also
contribute to the overall direction of the foundation. Already the GRASS
community feedback on the risk of relicensing has been taken very seriously
and contributed to us dropping the idea of contributor agreements.

PS. Sorry for missing Glynn's question about PSC voting on the first pass.
I have been skipping all the "suggested color function names" emails assuming
they were related to some esoteric detail of little interest to me. I have
taken the liberty of retitling this email.

Best regards,

--
Helena Mitasova
Department of Marine, Earth and Atmospheric Sciences
North Carolina State University
1125 Jordan Hall
NCSU Box 8208
Raleigh, NC 27695-8208
http://skagit.meas.ncsu.edu/~helena/

email: hmitaso@unity.ncsu.edu
ph: 919-513-1327 (no voicemail)
fax 919 515-7802

16

Helena,

I thought that I had explained a few times the need of having
a steering committee. I agree on not adding much overhead.

But so far I got only negative responses on this while the
issue that one reverts the changes of others isn't really
solved.

In fact we have nominations for the PSC but nobody said what
is next step. The first step is that people agree on *having*
such structure. Only then we can render the nominations into
something else.

As far as I remember only Michael and Glynn answered, both
pointing out that a PSC is not desired.

The big question is maybe if people are interested to join
the OSGeo efforts or not. If not, it should also be discussed
how to maintain this project in future. So far we have sponsorship
from ITC-irst (web site structure, partial funding of developers
working at ITC-irst) and Intevation (CVS, RT). But this isn't
granted forever. I see OSGeo as an opportunity to give GRASS
a stable (secondary) home.

As Frank pointed out: the comments here on the "contributors agreement"
already had major impact. So it is not true that OSGeo would take
the software and do something else with it (this even doesn't
make sense).

Here the steps as I see them currently:

step 1: do we want to join the OSGeo foundation, at least make GRASS
        a foundation project?

if yes/no to 1:
  step 2: do we want to establish a project steering committee for
          general decisions

if yes to 1 and 2:
  step 3: how do we render the nominations into members (sort of
          bootstrapping democracy)

if yes to 1, 2, 3:
  step 4: do the needed steps for incubation.

My emails so far:

ad 1:
  http://www.grass.itc.it/pipermail/grass5/2006-February/021101.html
  http://www.grass.itc.it/pipermail/grass5/2006-February/021127.html

ad 2:
  http://grass.gdf-hannover.de/twiki/bin/view/GRASS/ProjectSteeringCommitee
  http://www.grass.itc.it/pipermail/grass5/2006-February/021178.html
  http://www.grass.itc.it/pipermail/grass5/2006-April/thread.html#22185

as 3:
  we could follow the other projects. Bootstrapping PSC is a sort of
  dictatorial thing (selection), later people can be elected/removed etc.
  No need to reinvent the wheel, there are many successful open source
  projects out there as Frank pointed out.

ad 4:
  http://www.grass.itc.it/pipermail/grass5/2006-February/021445.html
  http://grass.gdf-hannover.de/twiki/bin/view/GRASS/ProjectIncubation

Maybe my role here is unclear: I don't feel priviledged to take
these decisions myself. But apparently this is partially expected... or
at least that I guide the process. If so, I would guide it versus the
foundation. However, in my opinion we first need to agree upon very
basic things - see above.

In the OSGeo Wiki I have written some documents for a potential
incubation (things which we should do also without OSGeo!):

http://wiki.osgeo.org/index.php/GRASS_Incubation_Progress
http://wiki.osgeo.org/index.php/GRASS_Provenance_Review

The code provenance review we partially did for the change to GPL in 1999,
but tons of copyright statements are missing. I have received a nice perl
script to semi-automatize this from Schuyler Erle which I am happy to
add to the tools/ directory. Obviously I cannot review a few thousand
files myself... but a code review is needed from time to time.

Well, let's start with item (1) from above list.

Best

Markus

On Wed, Apr 26, 2006 at 12:05:17PM -0400, Helena Mitasova wrote:

Frank, Markus,

if people on this list do not follow osgeo activities, it hard to
understand from emails that Markus posted
what is needed for GRASS project incubation, setting up PSC, etc. So I
am not surprised at all by Glynn's questions,
I had similar ones. So Markus, if you could let us know what needs to be
done - step 1.2.3,
maybe we will get it moving. We have nominations for the PSC but nobody
said what is next step - who votes
to set it up etc.
Frank, thank you for your explanation - this helps a lot - now we need
to know what is the next step after nominations.
And BTW, as I have already expressed to Markus, we should really keep
the management structures and procedures
to minimum (there already was a GRASS steering committee, GRASS
interagency committe, GRASS foundation
and soon everybody is sitting in meetings and nobody has time for
development and you also lose the freespirit
of open source development), so I am with Glynn on this, but
a minimal steering committee is really needed for reasons well explained
by Frank,

Helena

Frank Warmerdam wrote:
>Glynn Clements wrote:
>>Markus Neteler wrote:
>>>Instead of recursively reverted changes of other developers,
>>>we should come up with a design discussion and then *vote* on it.
>>
>>Who gets to vote? Anyone who wants to, only people who contribute
>>code, only people who will be affected by the decision, ...?
>
>Glynn,
>
>I will respond based on how the MapServer or GDAL/OGR PSC operate.
>There is certainly latitude for the GRASS community to define a PSC
>that operates slightly differently.
>
>Only the members of the PSC would get to vote. However, the
>discussion and voting would normally occur on the public project
>mailing list and anyone can express an opinion.
>
>>E.g. with a display architecture, the risk is that "application"
>>developers would vote for the ultimate graphics API which includes
>>everything provided by both OpenGL and PostScript and then some
>>extras, which consequently never gets implemented.
>
>Normally the practice is that someone interested in implementing
>a feature must prepare a proposal. This would be then discussed,
>and potentially revised by the original proposer based on feedback
>before a formal vote.
>
>The GDAL and MapServer (and Apache) practice is that anyone who
>votes +1 (ie. supporting the proposal) is also agreeing to help
>with implementation if needed. But for the most part the original
>proposer is responsible for implementing what they have proposed.
>This highly motivates proposers to only propose what they are
>prepared to implement.
>
>>>At least for such crucidal pieces of the code I would like to see
>>>less anarchy and a more formal approach.
>>
>>I'd certainly agree with the "less anarchy" part, although I'm not
>>sure that a "committee" is the answer. The mailing list is a perfectly
>>suitable forum; people just need to use it (the first thing anyone
>>heard about the alpha "enhancement" was a message informing everyone
>>that it had been committed).
>
>Note that PSC committee discussions would be occuring on the public
>mailing list. The PSC primarily provides a formal way of deciding
>whether to adopt a proposal when it is unclear. The proposal
>process is also very helpful in preventing the sort of surprise you
>seem to have run into.
>
>>A simpler solution would be to have defined maintainers for specific
>>sections of the code base. Developers would be expected to discuss any
>>non-trivial changes to another developer's section beforehand.
>>Maintainers would have more liberty to act within their own section,
>>but would still be expected to discuss more substantial changes,
>>particularly if the changes would be "visible" to users or other
>>developers (as opposed to purely internal changes such as refactoring
>>or optimisation).
>
>This is essentially the process taken by the GeoTools project. They
>have the GeoTools code base clearly broken into something like 10
>modules, and each module has a module maintainer that is responsible
>for their module, and relatively free to make internal changes as
>desired.
>
>I do think having module maintainers is a good idea if you have some
>sort of logical way of segmenting the code, end have folks willing
>to take on the responsibility for sections. But I think that having
>public discussions of anything that could affect users or other modules
>is important.
>
>I would like to stress that a PSC based process is used by many
>successful
>community projects. It is part of the Apache process for all Apache
>projects. It is already used by GeoTools and MapServer quite
>successfully.
>And with project specific variations it will be used for other OSGeo
>projects.
>This is not a radical idea. It is a "best practice" for open source
>projects.
>
>On a more meta level, I feel the GRASS community is not going out of it's
>way to support Markus as he tries to bring GRASS into OSGeo. He needs
>senior members of the GRASS community to get involved, and support this
>migration work. That means working on a PSC charter, following the
>"incubation process", helping with code copyright review, and
>participating
>in other OSGeo activities.
>
>The GRASS community has a lot of offer OSGeo and I hope OSGeo has a
>lot to
>offer the GRASS community. You can tailor GRASS's involvement and also
>contribute to the overall direction of the foundation. Already the GRASS
>community feedback on the risk of relicensing has been taken very
>seriously
>and contributed to us dropping the idea of contributor agreements.
>
>PS. Sorry for missing Glynn's question about PSC voting on the first
>pass.
>I have been skipping all the "suggested color function names" emails
>assuming
>they were related to some esoteric detail of little interest to me.
>I have
>taken the liberty of retitling this email.
>
>Best regards,

--
Helena Mitasova
Department of Marine, Earth and Atmospheric Sciences
North Carolina State University
1125 Jordan Hall
NCSU Box 8208
Raleigh, NC 27695-8208
http://skagit.meas.ncsu.edu/~helena/

email: hmitaso@unity.ncsu.edu
ph: 919-513-1327 (no voicemail)
fax 919 515-7802

_______________________________________________
grass5 mailing list
grass5@grass.itc.it
http://grass.itc.it/mailman/listinfo/grass5

17

Helena Mitasova wrote:

Frank, Markus,

if people on this list do not follow osgeo activities, it hard to understand from emails that Markus posted
what is needed for GRASS project incubation, setting up PSC, etc. So I am not surprised at all by Glynn's questions,
I had similar ones. So Markus, if you could let us know what needs to be done - step 1.2.3,
maybe we will get it moving. We have nominations for the PSC but nobody said what is next step - who votes
to set it up etc.

Helena,

Well, in fact the bootstrapping process is not entirely obvious. For
MapServer we had an issue with how to bootstrap a steering committee.
What I ended up doing was issuing a document describing the TSC and getting
all the folks named in the TSC to declare "+1" support for it (after a bit
of revision). Since it included a broad representation of the significant
developers contributing to MapServer it was accepted and we went from there.

My suggestion for GRASS would be to prepare a document for a PSC (perhaps
modelled loosely on MapServer or GeoTools or some other operational
project), discuss it on the list. Hopefully the document can be
adapted to address any serious objections. Then declare the PSC "in force"
when all of the initial members declare their support (via a +1 to the
mailing list for instance).

The key is to end up with a committee that the GRASS community respects
as being in charge, and that has a clear process to make decisions.

Frank, thank you for your explanation - this helps a lot - now we need to know what is the next step after nominations.
And BTW, as I have already expressed to Markus, we should really keep the management structures and procedures
to minimum (there already was a GRASS steering committee, GRASS interagency committe, GRASS foundation
and soon everybody is sitting in meetings and nobody has time for development and you also lose the freespirit
of open source development), so I am with Glynn on this, but
a minimal steering committee is really needed for reasons well explained by Frank,

I agree with the need to keep overhead modest. One of my goals for OSGeo is
to manage some of the overhead required for a legal entity in a way that
shares the load between many projects. I didn't have the gumption for a
"GDAL Foundation", and discussion of a "MapServer Foundation" was not able
to get off the ground for several years due to the overhead involved. But
with a shared infrastructure it becomes much more managable.

Of course, there has been a non-trivial amount of "committee overhead"
within OSGeo as Markus can attest being on the board, the incubator and
a couple other committees. We even these we try to keep overhead managable
and to "meet" in IRC which means you can do other work if you aren't
actively involved in a particular point of discussion.

For MapServer the TSC (originally it restricted it's mandate to technical
issues) has added some overhead. We now need to write up a document
describing substantial changes to MapServer (we call these RFC's) and
revise these based on review feedback. The voting is generally not a big
issue since we take the approach that two +1's from voting members is
sufficient to pass something as long as there are no objections. The main
downside there is that there is a 2 day wait before committing changes
that require an RFC and vote. We generally don't vote on bug fixes, or
very localized (non-disruptive) improvements.

One reason that we ask each project to come forward with it's own
"governance rules" is so that each project can adapt it's rules to
the realities of that project as long as it fits in the general sense
of an OSGeo PSC. That is that it has to be "in control", has documented
procedures that are followed, and is reasonably open to review and input.
One of it's key responsibilities is to ensure that code added to the project
is legitimately contributed (ie. watch for copyright violations).

While I realize details of the incubation process may not be of great
interest to everyone, there is a growing wealth of material on the incubation
process available at:

   http://wiki.osgeo.org/index.php/IncCom_Wiki

Details of the incubation process are firming up at:

   http://wiki.osgeo.org/index.php/Official_IncCom_Documents_(status)

The GRASS Status page is at:

   http://wiki.osgeo.org/index.php/GRASS_Incubation_Progress

Hmm, I see that the GRASS incubation status page is still based on
the original "request to incubate" form, not the status template.
Perhaps someone would like to help Markus overhaul the status page
to be based on this template:

   http://wiki.osgeo.org/index.php/Project_Status_Template

Folks are welcome to attend Incubation Committee meetings or join the
incubation mailing list, though currently only Markus has voting status
with the incubation committee. As is usually the case anyone with a
sensible point to make can be influential.

Best regards,
--
---------------------------------------+--------------------------------------
I set the clouds in motion - turn up | Frank Warmerdam, warmerdam@pobox.com
light and sound - activate the windows | http://pobox.com/~warmerdam
and watch the world go round - Rush | President OSGF, http://osgeo.org

18

Frank Warmerdam wrote:

> E.g. with a display architecture, the risk is that "application"
> developers would vote for the ultimate graphics API which includes
> everything provided by both OpenGL and PostScript and then some
> extras, which consequently never gets implemented.

Normally the practice is that someone interested in implementing
a feature must prepare a proposal. This would be then discussed,
and potentially revised by the original proposer based on feedback
before a formal vote.

The GDAL and MapServer (and Apache) practice is that anyone who
votes +1 (ie. supporting the proposal) is also agreeing to help
with implementation if needed. But for the most part the original
proposer is responsible for implementing what they have proposed.
This highly motivates proposers to only propose what they are
prepared to implement.

OK, that makes sense. At least, in general.

The problem with GRASS is that it is understaffed, in the sense that
the total amount of code is large relative to the number of active
developers. As a consequence, we can't afford to create too many
obstacles for potential contributors.

Also, there's no point in making formal proposals unless people are
going to review them, and reviewing proposals itself requires some
effort.

--
Glynn Clements <glynn@gclements.plus.com>

19

>Frank wrote:

The GDAL and MapServer (and Apache) practice is that anyone who
votes +1 (ie. supporting the proposal) is also agreeing to help
with implementation if needed. But for the most part the original
proposer is responsible for implementing what they have proposed.
This highly motivates proposers to only propose what they are
prepared to implement.

Glynn Clements wrote:

OK, that makes sense. At least, in general.

The problem with GRASS is that it is understaffed, in the sense that
the total amount of code is large relative to the number of active
developers. As a consequence, we can't afford to create too many
obstacles for potential contributors.

Glynn,

I will assure you that most projects feel understaffed, but I will
concede that GRASS has a very large code base in proportion to the
developer time available to work on it. I've been amazed at the
substantial rework that has been accomplished on GRASS in recent years.
But you must carefully consider fundamental changes as they require
revisiting a lot of code!

I would add that having a mechanism for new contributors to go through
to "get permission" can in some ways be enabling. With mapserver
outside folks used to propose ideas on mapserver-dev from time to
time but only get a bit of vague feedback. It was very hard for them
to determine if they had permission to proceed, or what.

Also, there's no point in making formal proposals unless people are
going to review them, and reviewing proposals itself requires some
effort.

Agreed. But it isn't critical that everyone on the PSC or off do
a careful review of a proposal. If it does not seem to affect anything
you have an interest in, you can just let it slide with an implicit
vote of "no opinion". It is important that at least a few people
go over the proposals. Hopefully for any given area of the code there
will be at least one person interested in possible effects to comment
and vote. In the case of MapServer it only takes two +1's to pass a
proposal if there are no objections. So a potential contributor does
need to make a proposal interesting enough to get two people to review
and give a +1.

One approach that GeoTools uses is they have an area in source control
they call "the spike" (I think). Which is basically an experimental area
that folks can freely work on new and radical stuff without affecting the
baseline source tree. For GRASS it is easy to imagine such an area for
new experimental contributed programs. How to use such a thing for library
changes is less obvious.

In the case of GDAL I have generally taken a very liberal approach to
letting people contribute new drivers as long as they aren't disrupting builds.

So I think each project can work to provide a play area for work-in-progress
without a complex process.

Best regards,
--
---------------------------------------+--------------------------------------
I set the clouds in motion - turn up | Frank Warmerdam, warmerdam@pobox.com
light and sound - activate the windows | http://pobox.com/~warmerdam
and watch the world go round - Rush | President OSGF, http://osgeo.org

20

One approach that GeoTools uses is they have an area in source control
they call "the spike" (I think). Which is basically an experimental
area that folks can freely work on new and radical stuff without
affecting the baseline source tree. For GRASS it is easy to imagine
such an area for new experimental contributed programs.

I think the idea of a semi-public (low barrier to entry) sandbox outside
the main CVS is a good one. The wiki addons are nice, but not really
collaborative. e.g. this would be useful for the final development of
v.in.gpsbabel and probably r.li (I'm not familiar with the r.li module,
but it seems like a good candidate from what I've heard). The unready
modules don't clutter the main .tar.gz package and lower the overall
"finish" of the main distribution while they are still maturing.

I think this will have to wait until we have moved the CVS to SVN:

1) fine-grain access to the semi-public repository is needed
2) There will probably lots of directories coming and going through
time. CVS is just too messy leaving old removed directories behind.

Another problem is someone will have to do the merge work once the
module is ready (but we already have to do that..). The PSC sounds like
a good channel for giving a new module the thumbs-up for inclusion in
the main release. The sponsors take on the responsibility to check that
it is merged correctly (if they don't just do it themselves).

Call it the experimental or contrib area, doesn't matter to me.

Coordination with the G.E.M.: Recommend that GEM integration be the
prefered checkin structure for the experimental section. This could
be finished while the module was already uploaded to the experimental
section.

How to use such a thing for library changes is less obvious.

Agreed.

Hamish