Like any language, the Scribble Protocol Language/Notation will need to evolve to capture new requirements. At the same time we need to ensure this process is carefully managed to understand the impact of adding new changes on existing users of the language.

Therefore this artice discusses some guidelines on how extensions to the language can be proposed, discussed and incorporated into the language.

Step 1 - Record the proposed change

The main goal of these guidelines is to ensure all of the proposed extensions to the language are correctly managed as independent changes. There may be many changes being evaluated in paralllel, with different people working on each, and therefore the ideas must be properly documented.

To do this we need to have a mechanism for managing the lifecycle of the change, from conception to implementation. The Scribble project's issue tracking system is ideal for this task:

1. Raise a 'Feature Request' in the Scribble project's issue tracking system
2. Associate the feature request with component 'Scribble Language', to enable all proposed language changes to be easily found
3. Identify the 'Affects Version' - this is the version of the language that the change will be applied to.
4. Identify the 'Fix Version' - this does not need to be completed at this stage, unless known
5. Description - this should ideally describe the reason for the change and a preliminary discussion on how this may be solved

The issue tracking system is also used to manage the development of the Java tooling, so the range of versions include the versions associated with the software (currently 2.0.x), as well as a set of versions that are applicable to the language (of the type Protocol-1.x). So ensure that you use the 'Protocol-1.x' style versions.

The 'Fix Version' is used to indicate the target version of the change. When the proposed change is initially recorded this may not be known, and may require first an understanding of the impact of the change, its dependencies on other proposed changes, etc. So this field can be filled in when more information is known.

Step 2 - Identify the dependencies between proposed changes

As previously mentioned, there can be a number of changes being evaluated at the same time, and some of those changes may be dependent upon one another - either because one is required by another, or because one may have an impact on the other.

It is important to identify links between proposed changes to enable appropriate planning regarding which releases the changes should be introduced, and the order of implementation (if in a single release).

Step 3 - Discuss the proposed change

Although the issue tracking system can be used to record discussions, if they are length and involve many people, this can bloat the issue and make it hard to see the concise decisions that have been made.

Therefore discussion should be held on the user forum: http://community.jboss.org/en/scribble

Once a forum thread has been started, its reference (URL) should be added to the feature request in the 'Forum Reference' field.

NOTE: These discussions are purely intended to explore how the syntax of the language should change, and any potential impact on the endpoint projection. Discussions on theoretical aspects of the change should be handled on the research mailing list.

Step 4 - Recording agreed solution

When the discussion thread reaches a conclusion regarding the syntax changes, and how it impacts other areas (such as projection), then this information should be transferred to the feature request in the issue tracking system.

Along with a description of the change, examples should be attached that demonstrate valid and invalid protocol descriptions.