More frequent CWE releases and CWE versioning

[Steven M. Christey-2]

All,

We are planning to release a new version of CWE on Tuesday, October 14.
But before we do so, we'd like to get your opinion on how we should label
things when CWE data changes.

This new version does not have the large number of changes that we saw
occurring between drafts.  The schema remains the same.  We've updated
a few dozen CWE entries and added a new entry, but otherwise the
content is the same.

For the foreseeable future, we are planning a more frequent update
schedule - currently estimated at once a month, although the frequency may
vary depending on "quality-based" criteria or external deadlines.

So, we now face a question of the best way to capture these ongoing
versions.

The CWE schema supports two separate elements that could be used for
versioning:

  Catalog_Version - a string

  Catalog_Date - a date

In the past, we've only used the Catalog_Version - so currently, it's
at "1.0."


We believe there are two main choices for how we can handle versions
in the future.  We wanted to get feedback from the researcher list
because you are some of our most active users of CWE.

The options are:

1) Versions for each change

   Use Catalog_Version to contain sub-versions for every new release
   of CWE, no matter how small the change; and use larger versions to
   reflect significant content changes, such as major changes to an
   important view.

   The Catalog_Date would be filled out, but only as a convenience for
   users, so that they don't have to go to the CWE web site to figure
   out what date CWE was released on.

   So, the new release would be labeled "1.0.1"

   The XML download would be cwec_v1.0.1.xml


2) Versions for significant changes

   Catalog_Version would not be modified if only small changes
   occurred, as will be the case for October 14.  We would only modify
   the version number when significant content changes occur, as
   mentioned previously.

   The Catalog_Date would be changed whenever content changed within
   the same version, so that people who care about the small
   differences can check to see if their copy of CWE needs updating.

   So, the new release would remain labeled "1.0", and the
   Catalog_Date would be "2008-10-14".  The XML download would remain
   at cwec_v1.0.xml.


By creating new versions for each change, including minor changes, this
would ensure that there is no confusion between copies of CWE; any two
parties who say they use "CWE 1.0.x" would be using the exact same data.
However, casual CWE users would not understand the rationale for why the
versions are updated, so they might update their data more frequently than
necessary.

By limiting new versions to significant changes only, then any version
change will send a strong signal that it's important for people to update
their copy of CWE.  People who care about minor versions can still use the
date field if they want.

Note that in either case, we will be providing version-to-version diffs on
the web site.

What would work best for you?  Do you expect to follow every single update
of CWE, or only the most significant changes?


Thanks,
Steve

[Steven M. Christey-2]

On Sun, 12 Oct 2008, Pascal Meunier wrote:

> IMO ideally you need two version numbers.  You need a schema/view
> version and a content version.

The raw XML already references the schema in the noNamespaceSchemaLocation
attribute, and we hope that the schema won't change so often.  So, I've
been viewing this as sufficient information.  However, we expect to force
a major content version change if the schema also changes significantly.

That said, we expect to be making small modifications to the schema in the
next month or so - basically, we want to add a couple new values to the
Introductory_Phase element.  We expect we'll have similar small schema
changes as we add new programming languages to the Language element under
Applicable_Platforms.

>  In option 1, a change in a view can be
> confused with a major change in individual CWE entries.

We will need to be more precise about what should constitute a "major"
change versus a "minor" change.  View maintenance is largely a matter of
modifying relationships between CWE entries (and/or editing the view node
itself).

> This is how it could work in practice:
>
> -The XML download could be named cwec_s1.0_c1.0.xml



The schema is currently at 4.0, so using your scheme, the download would
be named:

   cwec_s4.0_c1.0.xml

since the schema is currently at 4.0:

  http://cwedev1.mitre.org/data/xsd/cwe_schema_v4.0.xsd

If we go this route, I'd advocate listing the content version first, then
the schema version, since I'd expect that the content version would be the
most important to people.

So if we changed the version to 1.0.1, we'd have:

  cwec_c1.0.1_s4.0.xml

Either way, that seems like a lot of dots and numbers, so its not
aesthetically pleasing to me.

> -I suspect it would be better (less ambiguous) if the content version
> would never reset when you modify the schema or views, so if you had
> schema/views 1.0 and content 1.6, if you adopt schema/views 2.0 then the
> content version would be at least 1.6, possibly 1.7 or higher depending
> on the extent of changes.

I would expect this to be the case.  The schema and content versions are
closely related, but they are clearly separable in my mind.

When you talk about views changing, do you mean the XML downloads of
specific views?  Or when we change relationships within views?  I view the
latter as a content change.  The former is basically just part of our web
downloads that are automatically generated from the core XML.

> Files with only the differences or a list of updated CWEs between
> content versions would be a bonus.

The diff's will list the updated CWEs.  I don't think we can produce files
with only the differences at this stage, but we'll definitely consider it
for the future.

- Steve

[Pascal Meunier-2-3]

Steven M. Christey wrote, On 10/13/2008 09:28 PM:

(...)

> When you talk about views changing, do you mean the XML downloads of
> specific views?  Or when we change relationships within views?  I view the
> latter as a content change.  The former is basically just part of our web
> downloads that are automatically generated from the core XML.
>

I'm sorry, that was sloppy thinking on my part.  I was grouping schemas
and views together, whereas when you say "schema" you clearly have only
something like the XML schema definition in mind.  I thought it would be
interesting to separate changes in relationships defined in views from
changes in the CWE entries themselves, and to keep track of each
category separately.   The noNamespaceSchemaLocation attribute doesn't
allow for that.

Regards,
Pascal

[Steven M. Christey-2]

On Tue, 14 Oct 2008, Pascal Meunier wrote:

> I'm sorry, that was sloppy thinking on my part.  I was grouping schemas
> and views together, whereas when you say "schema" you clearly have only
> something like the XML schema definition in mind.  I thought it would be
> interesting to separate changes in relationships defined in views from
> changes in the CWE entries themselves, and to keep track of each
> category separately.

An interesting point - if you only care mostly about one view, then you'd
want to know what's changed within that view.  I've been considering
view-specific diff reports that highlight which relationships were added
or removed; these could be part of the larger diff.  Within the XML
itself, the individual view node could potentially record its own
"sub-version" that changes whenever the view changes (alternately, the
modification record in the content history could be updated).

Would people find it useful to be able to track when a view's
relationships have changed?

- Steve