Specification Change Management Plan

Technical (archive)
1

Hi everyone,

When answering a question from Tony Austin, I ended up at this link :
http://www.openehr.org/repositories/spec-dev/latest/publishing/CM/CM_plan/REV_HIST.html
(pick the latest version)

The question I have is about Chapter 7 & 8 (from now on called
document).

Is the description of the documennt what will be used for every
subproject of openEhr (with subproject in this case I mean project where
actually programming takes place) and is this considered a manual for
people who want to start programming openEHR like stuff under the
umbrella of openehr.org ?

What is the goal of the openehr project ? Does it want to something like
how Apache works (see
http://www.apache.org/foundation/how-it-works.html)
or does the openehr project want a different direction ?

If it is meant as the apache way and(which is what I read between the
lines) and the chapters are the "official way", you should probably
change chapter 7 & 8 to be the text of the how it works html file (with
some changes of course). Or point to a simple (html) file from the web
site describing the process within openehr.org and refer from there for
the people interested in reading the chapters 7 & 8.

Describing how something should work (related to a community, in this
case an open source community), must, in my view be kept simple.
If you skim through the document (what I did in the first place, since
there was a lot of text), people like me (= who likes to program and
never RTFM, unless really necessary) get scared and draw wrong
conclusions.

Too much formality is scary (at least for people like me) :slight_smile:

Hope no one (esp. Thomas) feels offended, since it is not meant that
way. (I admire the way you guys can write specs, if people ask me where
my specs are "Read the code" will be my answer).

2

Martin van den Bemt wrote:

Hi everyone,

When answering a question from Tony Austin, I ended up at this link :
http://www.openehr.org/repositories/spec-dev/latest/publishing/CM/CM_plan/REV_HIST.html
(pick the latest version)

The question I have is about Chapter 7 & 8 (from now on called
document).

Is the description of the documennt what will be used for every
subproject of openEhr (with subproject in this case I mean project where
actually programming takes place) and is this considered a manual for
people who want to start programming openEHR like stuff under the
umbrella of openehr.org ?

not necessarily. This CM plan was originally written mainly for the specification project, and will be adapted for more programming-oriented projects. But implementation projects won't have a very different plan - this plan I wrote based on plans used at a number of companies I have worked at, including banks, British Telecom, and large engineering companies in Australia.

What is the goal of the openehr project ? Does it want to something like
how Apache works (see
http://www.apache.org/foundation/how-it-works.html)
or does the openehr project want a different direction ?

this page is more or less Apache Software Foundation's change process definition.

If it is meant as the apache way and(which is what I read between the
lines) and the chapters are the "official way", you should probably
change chapter 7 & 8 to be the text of the how it works html file (with
some changes of course). Or point to a simple (html) file from the web
site describing the process within openehr.org and refer from there for
the people interested in reading the chapters 7 & 8.

this plan is under modification right now actually, and some details will change. We will also publish a simple, clear set of web pages so that people can understand what the process is. The ASF page seems like a good model.

Describing how something should work (related to a community, in this
case an open source community), must, in my view be kept simple.
If you skim through the document (what I did in the first place, since
there was a lot of text), people like me (= who likes to program and
never RTFM, unless really necessary) get scared and draw wrong
conclusions.

Too much formality is scary (at least for people like me) :slight_smile:

Hope no one (esp. Thomas) feels offended, since it is not meant that
way. (I admire the way you guys can write specs, if people ask me where
my specs are "Read the code" will be my answer).

ah, well, you will discover there are limitations to that approach in the long run (as I am sure you are aware;-) The openEHR community may well get quite large, and we do need to write good quality documents. But we are also dedicated to making things simple and understandable as well - this doesn't mean throwing out our base documents, it means writing short & shart summaries on the website. We need people in the community to tell us what to write (and offer to write things themselves if so motivated), so this is good feedback.

- thomas

3

Thanx for the answer I was looking for :slight_smile:

>
>
this plan is under modification right now actually, and some details
will change. We will also publish a simple, clear set of web pages so
that people can understand what the process is. The ASF page seems like
a good model.

I can remove the apache stuff from the page and attach that file to
jira, if you want.

>Describing how something should work (related to a community, in this
>case an open source community), must, in my view be kept simple.
>If you skim through the document (what I did in the first place, since
>there was a lot of text), people like me (= who likes to program and
>never RTFM, unless really necessary) get scared and draw wrong
>conclusions.
>
>Too much formality is scary (at least for people like me) :slight_smile:
>
>Hope no one (esp. Thomas) feels offended, since it is not meant that
>way. (I admire the way you guys can write specs, if people ask me where
>my specs are "Read the code" will be my answer).
>
>
ah, well, you will discover there are limitations to that approach in
the long run (as I am sure you are aware;-)

Don't totally agree here (depends on the area you are talking about).

You can probably define 2 set of rules :
1) The meritocracy (as described in the how it all works document)
2) Legal issues

1 almost never fails, although there are scenarios that it does (eg
Apache Avalon, but that was mainly clashing ego's and different views on
architecture).
The main reason this not failing, is the principle : if you veto a
decision, you have to explain why, if you don't the veto is void.
A veto can happen for votes and for eg commits (commit mails are
important at apache, also for being able to have the necessary
oversight, hope bitkeeper supports that)

Also the main reason everything works "automatically" is that most
people have common sense and there is huge degree of trust amongst each
other (you have to assume no one is there to mess up everything on
purpose)
Eg The Episode discussion (assuming I have the proper access to change
the specs), I could (technically) simply add the Episode stuff the way I
see fit. Since I know you and others now way more about all those stuff,
I will automatically discuss this first, before making the change. If I
have the attitude "I know it all and I know it better, even though I
don't" I will not last long in a community and move away automatically.

Most difficult and not to be underestimated is 2, but that is probably
for another thread :slight_smile:
If you are interested I can put down some things that are needed, so
openehr.org keeps the owner ship of the source code.
What is the license you want to use for openehr deliverables (meaning
the code) ?

The openEHR community may
well get quite large, and we do need to write good quality documents.
But we are also dedicated to making things simple and understandable as
well - this doesn't mean throwing out our base documents

That's why I changed my opinion from removing those chapters to
referring to them from the simpler page :slight_smile:

, it means
writing short & shart summaries on the website. We need people in the
community to tell us what to write (and offer to write things themselves
if so motivated), so this is good feedback.

That's the "send a patch" spirit, which is good :slight_smile:

4

To add a few more things to this discussion:

  • The openEHR Foundation will define / has defined the following projects:

  • specification (already exists)- knowledge (there is already a BitKeeper repository of archetypes; this will be extended to other knowledge resources)- and then a number of implementation projects, e.g. ADL parser (exists),…

  • the CM plan which you have seen, and which is being reworked applies to the specification repository at least - this is where we need a lot of discipline and we have to be careful, for obvious reasons

  • however, this CM plan was derived from software plans I have used in the past in a number of situations, and is a fairly typical (if simplified) plan for change management used in any large company or institution developing non-trivial software. You can buy a number of books about “software configuration management”, and you will find at least a dozen well-known IEEE standards relating to CM, testing, software audit etc

  • The CM plan is therefore a pretty good starting point for implementation projects in openEHR. But any particular project may choose to modify it to suit their own needs, particularly the CR workflow shown in the flowchart - most implementation projects will not have their own ARB for example, they will just have a group of developers.

  • However, some aspects need to be fairly standardised, in order to make the whole gamut of openEHR projects (i.e. projects that are run inside of openEHR.org) to newcomers - or people who will work on multiple projects. These I believe will include:

  • a standard Problem Report (PR) lifecycle

  • a standard Change Request (CR) lifecycle

  • a standard tool/environment for creating and accessing CRs and PRs. CRs need to be able to be created and viewed in a standard way by developers, whilst PRs need to be created and viewed in a known place and in a sensible way by users. (Note that developers can create PRs if they want, but will usually document the problem relating to a change they are working on in the “problem description” field of a CR instead). PRs are just a public problem-logging and reporting interface.

  • a standard version and change management toolset/environment. Currently for this we use BitKeeper in hosted open logging mode; also a toolset that supports “change sets”, which is a minimum basic semantic for managing source and documentation repositories. BitKeeper excels at this. (For those interested, the Linux kernel developments are managed under BitKeeper, and hosted on the same server as the openEHR projects).

  • I would encourage the basic concept that only a member of a project team can a) create a change request, and b) make any change to the project repository. This simply means that the team always knows who is in it, and has agreed among themselves that they can make modifications. Non-team members proposing sensible modifications are likely to be included into the team.

  • it is usually beneficial of the top level directory structure of implementation projects is fairly similar if not the same

  • it is usually helpful if the same build methods/tools such as make, ant etc are used to reduce confusion across projects

  • a standard way of disseminating the software to users, particularly binaries (i.e. make it easy for non-IT users)

  • a standard open source licence. Based on advice from people on the open source health care alliance (OSHCA) some time ago, we switched to using the Mozilla tri-license, which is really jjust a meta-license allowing the user to nominate GPL, LGPL, or MPL as the licence they use the software under. I am sure more discussions will occur about this subject, but I think the current position is at least reasonable for the moment if not final.
    These of course do not apply to people doing openEHR developments outside of the openEHR environment, e.g. on sourceforge, in their own compnay etc - the above just applies to public developments undertaken by the openEHR Foundation, on openEHR.org (so to speak). These include necessary projects - the specifications, archetypes, and reference implementations, and may also include other implementations from people who want to work in the same framework. Everything on openEHR.org however does have to have a clear conformance statement, and ultimately pass the relevant conformance tests, so that users of that component know it is safe to use for interoperability, data safety, security etc.

We have of course quite a way to go yet to attain all of these “norms” - and we are working on solutions with various people with respect to tools, improving the website, automating problem reporting and change requests and so on.

  • thomas beale

  • If you have any questions about using this list, please send a message to d.lloyd@openehr.org