Three Issues in the Use of Versioned Hypermedia for Software Development Systems Tien Nguye

Three Issues in the Use of Versioned Hypermedia for SoftwareDevelopment SystemsTien Nguyen,Satish Chandra Gupta,Ethan V.MunsonMultimedia Software LaboratoryDept.of EECSUniversity of Wisconsin-MilwaukeeMilwaukee,WI53211USAtien,scgupta,munson@Abstract.The Software Concordance project is extending the concept of literateprogramming with research on how modern document and hypermedia servicescan improve software development environments.The Software Concordanceeditor is both a syntax-recognizing Java program editor and an XML documenteditor.It has a uniform document model,based on XML,that lets Java sourcecode documents include both hyperlinks and inline multimedia documentation.The next step for the Software Concordance project is to enhance the editor withversioned hypermedia services in order to support sophisticated analysis and vi-sualization of relationships among software documents.This article discussesthree important issues for versioned hypermedia in this context:identificationof the versioning infrastructure that will be required;exploration of how ver-sioning information can be used to detect non-conforming documents;and theextension of versioned hypermedia to handle software configuration manage-ment.1.IntroductionWhen software engineers design and implement large-scale systems,they produce a large variety of software artifacts such as requirements documents,feasibility studies,design specifications,source code,module documentation,test plans,bug reports and sales plans. One challenging task for software engineers is to manage this collection so that the infor-mation can be quickly accessed and consistently organized.An important aspect of this task is to capture and manage the logical relationships among software documents.It is not uncommon for a large-scale software system to have hundreds of artifacts and thousands of implicit and explicit relationships,all evolving over time.The task of keeping these artifacts and relationships semantically consistent is not easy.The lack of powerful tools for document and relationship management forces developers to use ad hoc methods,including paper notes or memorization,which can lead to cognitive overhead and errors.This problem hinders developers from having a full understanding of the system and reduces their effectiveness.The Software Concordance is a software development environment that is attempt-ing to address the relationship management problem for software documents by provid-ing:a common document model that helps source code documents interoperate wellwith other software documents,afine-grained revision control model for software artifacts and their relationships, an extensible set of relationship types anda set of tools for analyzing,retrieving,visualizing and maintaining them.We have implemented a Software Concordance editor that uses a uniform document model to integrate program analysis and hypermedia services for both program source and documentation[15].This system is both a syntax-recognizing editor for Java pro-grams and an XML document editor.While there are a number of interactive program browsers in existence[8,25,32],we believe that the Software Concordance is thefirst system to make source code documents behave as hypermedia documents while still pro-viding interactive program analysis(lexing,parsing,and type checking)and supporting interactive editing.We have begun work to implementfine-grained version control of software doc-uments and their relationships(as represented by hyperlinks).This is an important step because software documents are not static,but rather evolve over time,and the relation-ships between software documents are also dynamic.Thus,the Software Concordance system will be a versioned hypermedia system.This paper describes three important issues that have arisen as we add support for versioned hypermedia to the Software Concordance.Two of the issues arise from our interest in conformance analysis.Conformance is our term for the state where a set of documents are in agreement with each other. Conformance analysis is the process of determining whether or not documents conform to each other.Conformance analysis is related to the well-known process of requirements traceability[28,p.261],but it has broader applications than just requirements tracing. For example,issues of conformance also arise between source code and bug reports and between design documents and user manuals.Thefirst issue that we address is the specific set of hypermedia services that are necessary to support conformance analysis.Secondly,we have investigated how to au-tomate aspects of conformance analysis using hypermedia versioning information.The final issue that we discuss is the relationship between hypermedia versioning and software configuration management.This article is organized into four sections,of which this section is thefirst.The next section briefly describes the Software Concordance project,including its motivation, the current editor prototype,and its future directions.Section3discusses the three issues for versioned hypermedia,while Section4is a conclusion.2.The Software Concordance ProjectThe Software Concordance project is motivated by the observation that software engineers have difficulty maintaining semantic consistency among their many documents.Our re-search is focusing on two particular sources of difficulty.First,source code documents interoperate poorly with the many other types of software documents.Source code documents are written and managed as simple text documents using specialized text editors,often in integrated development environments (IDEs)that include interactive program analysis.Other software documents are produced using a variety of tools such as word processors,graphics editors,and specialized en-vironments for project planning or graphical design languages such as UML[30].In general,these tools and the documents they produce interoperate well.However,source code documents and the IDEs used to edit them do not.Second,the relationships among software documents are usually implicit and thus cannot be browsed,navigated,queried,or analyzed systematically.This is particularly true for source code documents,whose lexical and syntactic rules hinder the use of hy-perlinks,the most natural means for representing relationships among documents.To address these problems,we seek to demonstrate that it is possible to create a new kind of software development environment in which:All software documents,including source code,are Web-compatible and able to include hyperlinks and embedded multimedia elements as documentation.Some software documents(such as source code)will be suitable for specialized analyses (such as compilation),but these analyses will not hinder interoperability.A variety of document views will be available in order to support the variety oftasks that a programmer performs.For example,programmers may want to hide distracting multimedia documentation or may benefit from novel“fish-eye”pre-sentations of source code.The environment will provide analyses and visualizations of the graph of hyper-links among the software documents so that developers can answer important questions related to such issues as requirements and bug tracing.Programmers will continue to have high-quality,interactive program analysis built in to their editors and will not be forced to use unnatural top-down(or syntax-directed)editing techniques.This vision for software development is similar in spirit to that articulated by Knuth for literate programming[20].Where Knuth envisioned a single document encompassing both the implementation and documentation of a system,the Software Concordance pic-tures a large collection of documents,linked with hypermedia technology into a literate whole.2.1.The Software Concordance editorThe project’sfirst application is an editor for Java source code and XML documents.The Software Concordance editor is implemented in Java with the Swing user interface library, and like most Java programs,runs in a variety of environments.Program analysis(lexing, parsing,and type checking)is provided by the Fluid program analysis system[11].A screen dump from an editing session is shown in Figure1.This session’s right-most window shows part of the implementation of an A VLTree class,specifically the simpleLeft method.The source code has been pretty-printed automatically using infor-mation from syntax analysis.The details of how the code is pretty-printed are controlled by a simple style sheet.Appearing above the method’s source code is some multimediaFigure1:Screen shot of the Software Concordance Systemdocumentation,including a diagram of the simple left rotation operation,a textual de-scription(but not a comment),and buttons that control an audio clip of the implementor explaining details of the implementation.On the left,the developer has another window open on the same source code document.This window shows the entire class,but using a style sheet that hides the method bodies and multimedia documentation so that only the class interface is visible. This is simply another view of the same information shown in the rightmost window.The two views are different only because they are presented using different style sheets.The developer can edit the document through either window and any changes will appear in both.The center window shows a design document for the A VLTree class.This window was brought up because the developer clicked on the word“simpleLeft”in one of the other windows.This word happens to be a hyperlink that points to the“Simple Left Rotation”heading in the design document.This heading is itself a hyperlink that can be followed back to the simpleLeft method in the class’s source code.The close integration between source code and design documents seen in this ex-ample is possible because the Software Concordance editor uses a uniform document model for all software documents.Both Java and XML documents are represented using the abstract syntax tree data structures of Fluid,but the editor accesses these structures through a facade that hides most of the complexities of program analysis.Gupta[15] describes the document model and its implementation in detail.The Software Concordance editor is thefirst program editor with integrated analy-sis services to support inline multimedia documentation and hyperlinks in source code.It can be contrasted with several other types of program editing and browsing environments. Programming environments like the Cornell Program Synthesizer[33],Pan[5,35], Ensemble[14],and Mj¨o lner[19]have powerful integrated analysis services butno support for multimedia or hyperlinks in source code.Software management environments such as SODOS[17,18],DIF[13]and Hyper-Pro[24,25]can maintain the relationships between documents from all phases ofthe software development process,but they do not support source code analysis. Program browsers and visualizers such as CHIME[8],the Variorum[6]and ShriMP[32, 39]exploit program analyses to provide novel and informative views that help de-velopers understand their systems.These systems provide interactive browsingbut do not support interactive editing and their analyses are performed in a batchmanner.Perhaps the system most similar to the Software Concordance is Desert[29],a software development environment that integrates a variety of tools through broadcast messages.It includes a common editor based on FrameMaker[1]that integrates program editing with editing tools for design diagrams and user interfaces.Desert views all of its artifacts as documents and achieves some of the integration and presentation features that we seek.However,Desert’s design deliberately avoids imposing a uniform document model and thus its level of integration falls short of our goals.3.Three issues3.1.Versioned hypermedia infrastructureWhitehead’s dissertation provided an organized list of requirements and goals for the hy-permedia versioning domain[37,chap.7].This list is also valid for hypermedia systems that are designed to support software development.However,to address conformance analysis and automatic relationship management adequately in hypermedia systems,sev-eral specific features are necessary.3.1.1.Versioning in Open Hypermedia SystemsA large-scale software development process produces a huge set of software artifacts, in many different computing environments,using multiple procedures and tools.This heterogeneity hinders document interchange and accessibility.An open hypermedia system(OHS)can handle this heterogeneity by providing mechanisms to integrate third party applications through both data and control integra-tion.This is an important advantage over embedded hypermedia systems(such as the HTML-based Web)for a software development environment(SDE)and it results primar-ily from the externally represented and managed relationships.This key characteristic addresses the automatic relationship management problem,which is crucial to software development[2].When relationships among documents are represented externally,they can be maintained and analyzed without modifying the documents.Different sets of hy-permedia anchors and link structures can be created according to the needs of users asthey perform different tasks.Another substantial disadvantage of embedded hypermedia systems is that the versioning of links is completely subsidiary to the versioning of the content.Open hypermedia systems can be broadly divided into two different approaches: link servers and open hyperbase.The goal of link servers[27,12,3]is to provide third-party links among a set of documents.The Link server approach is characterized by the use of third party viewers to present and store the contents of external objects[26].An open hyperbase[16,38]stores link information but provides storage for the content of ob-jects as well.The versioning frameworks of the existing open hyperbases are notflexible enough for SDEs,which have complicated data models and requirefine-grained version control.Implementing versioning on link servers is more complex because of the need to maintain synchronization between the versioning of external objects(performed by third party applications)and the versioning of hypermedia structures.However,this gives SDEs theflexibility to employ any revision control or data model that suits their goals. In brief,versioning of link server systems is necessary to provide automatic relationship management in SDEs.3.1.2.Requirements on anchorsThe notion of“anchors”varies from system to system[37],but anchors always denote regions of interest within objects in a hypertext system.In version space,as software documents evolve into new revisions,the regions of interest also change.These changes in documents may result in the non-conformance among software documents.In order to capture these changes and reflect the revisions of documents,anchors must also be versioned.SDEs also require support for both object-based and view-based anchors.View-based anchors are defined on the presentation(or view)of an external object.In an OHS,this presentation is the responsibility of a third-party application.An advantage of view-based anchors is that they can be defined for objects whose storage representation cannot be modified to include anchor information.They also allow link-based navigation among different views of the same document.This is a useful characteristic in a SDE that integrates third-party tools.In contrast,object-based anchors are defined on the underlying content of the objects and require either that the storage representation of the objects be able to describe anchors or that the OHS be aware of this storage representation.Object-based anchors will generally be visible in any view of an object.For an SDE,they have the advantage of correct semantics,because the logical connection between objects is not just an artifact of particular presentations.3.1.3.Requirements on linksSDEs also have requirements for links,because we assume that links are the representa-tion of logical connections between software documents.SDEs need typed links,flexibil-ity in the arity and directionality of links,and versions for links.Links must have types in order to represent the nature of the relationships among software documents.Relationship types can carry important information about the se-mantics of a relationship that can be exploited in later analysis.For example,“complains about”and“comments on”are two relationship types.The fact that A“comments on”B is essentially neutral.In contrast,when C“complains about”D,it is clear that a problem plaints require a response,while comments do not.While these example re-lationships are sensible,it does not appear useful to attempt to define a single taxonomy of link types for all situations,because the set of link types needed will depend on the software process used by each development organization.Rather,it must be possible for developers to define relationship types appropriate to their chosen process.Linking mechanisms that support a variety of link arities and directionalities are necessary because of the complexity of relationships among software documents.Non-directional links may be useful to connect examples of the same design pattern or uses of the same external library.Directional links can better represent causal relationships such as those between requirements,design,and implementation.While simple binary links will certainly be common,it is easy to envision the need for multi-links:a set of requirements may together motivate a set of design choices.Secondly,the developers must be able to define any kind of directionality of a link.A link must be a multi-link.An empty link should be allowed so that users can later on define its component anchors.Finally,links must be versioned.Some versioned hypermedia systems do not pro-vide versioning directly on links[24,31].Instead,changes in link structure are achieved by placing links inside containers that are versioned.This approach is not suitable for conformance analysis since the analysis requires to track individual links’evolution,and properties of links need to be updated over time.3.2.Conformance analysisSoftware systems evolve over time as the system is constructed from scratch and then as the system goes through a series of release versions.Thus,any system which purports to help with the management of software documents must support this evolution.We are particularly interested in helping developers detect when different software documents become non-conformant as the system evolves.Our current solution to this problem uses typed links along with versions and timestamps for anchors and links.3.2.1.RepresentationAs discussed in the previous section,the inter-document and intra-document relationships can convey important information about the semantics of the connections among software artifacts.In general,the relationships are among parts of documents,rather than entire documents.To achieve thisfine-grained representation,the SC document model provides a notion of linking between structural units.A structural unit is a fragment of a software document that is used to encode a concept such as a sentence,a paragraph,a section in software documentation or a statement,declaration,or class in program sources.It is represented by a node in the SC document tree.To capture the evolution of the relationships between documents,links in SC are typed and versioned.In general in SC,links are semantically directional but can be navi-gated in any direction and may connect more than two anchors.They are divided into four broad categories and the category affects both directionality and the number of anchors linked.Non-conformance links are intended to support navigational relationships that have little or no relevance to determining agreement between documents,such as table of contents and index links.Non-conformance links are n-ary,their direction is user-specifiable,and they are not used in conformance analysis.Non-causal links are n-ary and non-directional.They participate in conformance analysis.Causal links are used to represent semantic dependencies between entities where one document“causes”another.They have named types(such as“requires,”“specifies,”and“responds to”)and are always binary and directional.The dis-tinction between causal and non-causal links is important because causality can provide clues useful in conformance analysis.For example,item A in a design document may require the use of class B(A causes B)and function C may re-spond to bug report D(D causes C).Multi-causal links have two special associated sets:the source set and target set.This type of link is useful in the cases that a causal relationship has multiple sources and targets.Like causal links,they are directional and typed,but they are n-ary rather than binary.3.2.2.Anchor and link versioningAnchors in SC denote the regions of interest within a document and are versioned.But unlike some hypermedia systems,SC anchors are object-bound and view-independent.As an initial experiment,anchors are positioned at the structural unit level within a document. In version space,when the software documents evolve,the anchors might change as well, creating new versions.Anchors may also change when users redefine their positions in the documents,thus changing the semantic content of any links that use those anchors.Links in SC are also versioned,since a link is a set of anchors and the membership of the set may change over time.Thus,each anchor or link has a version tree.Every addition,deletion or replacement of an anchor for a link causes a new version of the link created.3.2.3.Conformance graphThe nodes and links form a general hypertext graph.An important related graph is the conformance graph,whose edges are the conformance links plus the structural relation-ships within the nodes,which are tree-structured documents.The conformance graph and its links have some important characteristics:The conformance graph must be acyclic with respect to causal links,because cy-cles would imply that a node causes itself.–The structural relationships within nodes are part of the conformance graphbecause a document element cannot have a causal relationship with any ofits ancestors.Such a relationship would imply that the element was caus-ing itself.Since causality is logically transitive,the structural relationshipsmust be part of the conformance graph when checking for cycles.Conformance links must connect anchors is a sensible way:–Non-causal conformance links must connect at least two anchors.–Causal links must have both a source and a target.–Multi-causal links must have non-empty source and target sets.The transitive and reflexive closure of edges corresponding to causal links definesa partial order set(poset)on a subset of nodes.The minimal elements of this posetare called source nodes and maximal elements are called sink nodes. Preventing cycles in the conformance graph will be a challenging task.It implies either that some information about the internal structure of a node must be visible to outside agents or that the conformance analysis will have to inspect the internals of a node.3.2.4.TimestampsIn SC,the representation of anchors and links uses standard concepts such as identifier, attributes and values as well as version information including version ID,version creator, and a timestamp.In addition,links must have a validation timestamp that records the time when the link was last validated by human inspection.When a link gets updated to a new version,the validation timestamp is copied from the previous version,even though validation predates the creation of the version.We expect this to simplify conformance analysis.3.2.5.Non-conformance ratingsWe have developed a scheme for detecting possible conformance problems in software document relationships based on the timestamps of anchors and links.This scheme pro-duces a numeric rating of the likely seriousness of the problem called the non-conformance heuristic value.They are on a scale from zero(likely conformance)to ten(likely non-conformance).However,these numbers are just heuristic values and have yet to be val-idated systematically.The detection scheme starts from non-causal links among source nodes and proceeds through causal links in a link-by-link manner.Causal links Causality implies a partial ordering in time.This partial order results from the fact that if causes,then must have occurred before.In the case of causal links,three timestamps are relevant:,the version timestamp of the source anchor;,the version timestamp of the destination anchor;and,the validation timestamp of the link.We have made a case analysis of the order of these timestamps,defining conformance ratings for each case,as shown in Table1.For example,if then the destination is newer than the source and the link relationship was validated by a human sometime after the last changes to both and the rating is zero.In contrast, if then the destination has changed since the last validation and the rating isfive(5).We have arrived at these ratings only by human judgement and makeTime Relationship CommentsNear full validity:src is newer thandest,but relationship has been validated5Likely problem:src has changed undetermined and relationship is not validated Table1:Non-conformance ratings for causal links based on various time rela-tionships between the anchors and the validation of the link.no claims of empirical validity.A correct and useful formula for these ratings remains an open question and will probably require empirical research.Non-causal links When causality is not available to provide clues,we turn to a more formulaic approach.Assume that a non-causal link connects anchors and let be the timestamp of the anchor.Then,if there exists any such that thenOtherwise,.is an adjustable parameter representing the minimum rating when the timestamps suggest that a problem exists.The idea is that this minimum rating may be affected by other factors such as the frequency of changes to the link’s anchors.3.3.Software configuration management and versioned hypermediaSoftware configuration management(SCM)is the discipline of managing the evolution of large-scale software systems.A SCM system records the composition of versioned software products as they evolve into many revisions and variants,maintains consistency between interdependent components,reconstructs previously recorded software configu-rations,builds derived objects from source,and constructs new configurations based on descriptions of their properties[4].The basic element of a SCM system is the software object.A software object can be afile(infile-based version control systems)or a smaller structural unit(infine-grained version control systems).The representation of software objects varies between different systems and they can be stored as textfiles or as syntax trees or graphs.Software objects have various types of logical relationships.The focus of a SCM system is on com-positional and dependency positional relationships organize software objects structurally,into larger composite objects.Dependency relationships establish di-rected dependencies between source objects and target objects.Examples of dependency relationships are import and include dependencies between modules and build dependen-cies between source code objects and compiled executable objects.A typical SCM maintains the evolution of a software product through the inter-play of two separate spaces:product space and version space.Product space describes。