The Software Engineering Handbook (SWEHB) web site was started in 2010. It was built on a Confluence Wiki platform by Jon Verville from GSFC. There were a number of plugins and macro packages used to built out the rich capability in the product. It was initially an internal to NASA site.
It was anticipated that revisions to the NPR7150.2 would be used to update the SWEHB and that only one version, in space 7150, based on the most current NPR, would exist. In 2017 the second version of SWEHB was born. It was based on NPR7150.2B in the space SWEHBVB. In 2018 work began on a third version of the SWEHB in space SWEHBVC. The most current version is based on NPR7150.2D and is in space SWEHBVD.
The architecture of the SWEHB sites is discussed on this page. It includes the basic Confluence Platform, add-on software like plugins and macro bundles, and a small amount of user (NASA) written macros that give the SWEHB its look and feel.
Additional documentation including Style Guides for certain types of pages are included as pages under this page.
Children Display
all
true
excerptType
simple
1.1 User Access
Access to the SWEHB is granted to anyone who can get to it through the NASA network as well as anyone on the world wide web through the URL: SWEHB.NASA.GOV. It is not necessary to log in to Confluence to use the SWEHB. Users may browse the content as Anonymous users. This access to content allows users to view content and download attachments. Editing and content creation is restricted to a small number of developers and curators who have Confluence logins and are in the appropriate group of editors.
Div
id
tabs-2
2. Platform
The SWEHB uses the Wiki from Atlassian Software. This Wiki is Confluence. It is simple to use but made more powerful with the addition of plugins and macro software.
Originally, SWEHB was deployed in GSFC on version 2.x of Confluence. By 2017 the SWEHB had been moved from GSFC to MSFC. Over the years the platform was upgraded many times by Atlassian. The system was upgraded to version 7.4.4 on Nov 20, 2020.
Currently, the platform is on virtual servers at MSFC and maintained by the IT organization there.
2.1 - Server
Confluence runs on a JAVA virtual server.
Operating System is Unix.
Application Server is Apache Tomcat.
2.2 - SQL Server
Confluence stores content in a My SQL database. All content is stored in database records using a KEY to identify what space the content belongs to. This means that multiple spaces can be stored in the same database. See tab 5 for a list of current spaces and their KEYs.
2.3 - Confluence
Initially, Confluence 2.x was used to develop the SWEHB in 2010. Subsequently the version of Confluence was updated to the current 7.x.
Div
id
tabs-3
3. Plugins and Macros
Plugins and Macro Bundles give the Wiki additional capabilities beyond what comes with Confluence. The plugins and Macro Bundles currently in use in the SWEHB.
3.1 Scaffolding
This plugin allows for identifying variables and storing values for the variables in Confluence pages. Once the values are embedded in the page, they can be used by other plugins and macros to enhance the value of the content.
For example, in SWEHB, data on references is collected and stored in SWEREF pages:
Link - URL for the reference
Title - Title of the referenced document
Citation - additional information about the reference such as, author, publisher, dates of publication, etc.
Notes - other descriptive information of interest
Affiliated SWE - internal page references within the SWEHB where the reference is called out
This plugin uses data collected in the Scaffolding plugin and stored in pages. The reporting plugin allows the developer to select values, sort data, and build reports to display the selected data in a meaningful way for the viewer.
For example, in SWEHB, the References section of SWE pages contains a report listing of references mentioned in the page, or having an obvious relationship to the page.
User macros are custom developed by the SWEHB maintenance staff.
Excerpt Include
User Macros in SWEHB
User Macros in SWEHB
4.2 Macro Packages
Macro packages are used to add capabilities beyond the native capabilities of Confluence. In SWEHB, these macro packages include:
Macro usage
Unused macros
The following macros are provided by user-installed apps and are not used on any pages (not including pages in archive spaces). This information is helpful if you're about to disable or remove an app and want to make sure its not used on any pages.
This list shows how often each macro is used in your site. We've organised the list by the app that provides the macro, and included both user-installed apps and apps bundled with Confluence.
The content of the SWEHB is contained in the various spaces that have been created over time. Each version of NPR7150.2 has a unique space for it's content.
5.1 Spaces
The original SWEHB was implemented in space 7150. Over time, spaces were added to accommodate more versions of NPR7150.2. At present, 4 versions of the SWEHB are in use:
The copy of the SWEHB on the Production server is where all content maintenance is performed. When testing of Confluence and platform level software releases need to be performed, a copy of the production content is put onto the Staging server. Testing of the platform software changes is then done to make sure there are no regression issues between the software running on Production and Staging. If there are no issues, Production software may be updated.
Macro Changes
Any changes to User Macros are made first on the Staging server. Once the changes are tested and proven, the macro code is manually copied to the Production server. Backup of macro code is the responsibility of SWEHB maintainers and MSFC IT so that a trustworthy method of reverting to Known Working Code is maintained.
Reviews on References
All references are updated as changes are brought to the attention of the SWEHB Maintainer. An annual review of all references is made to ensure that the appropriate version of each reference is available through a live (not redirected) link. As a part of this review, a change history on the reference is maintained.
See References in SWEHB for details on how references are handled and maintained.
New Versions of the SWEHB and NPR7150.2
As each new version of the NPR are released, new SWEHB versions are built and released. Each new release of the SWEHB is contained in its own space on the Confluence Server. At a high level, as each SWEHB version is built the following maintenance is performed on the new space:
A new space is created on the server along with a new theme (header and footer materials).
A full copy of the prior version of the SWEHB is copied into the new space.
All internal links on all pages are reviewed for referential integrity (point to appropriate pages in the space).
All changes from the NPR are reviewed and made on the appropriate pages.
SWEs are added as necessary,
Deleted SWEs are moved to the Retired SWE portion of the Protected Area.
Changes to SWEs are made as appropriate.
Applicability Matrix information is updated.
All pages are flagged for Content Review by a SME. Changes are made and reviewed as necessary.
All quotations are flagged and checked to see that the current source document actually contains the quotation. For quotations that have changed in the source document, the SME for the SWE or Topic is notified to update or remove the quote.
All diagrams and external materials are reviewed for applicability. Old materials are removed. New or changes to existing materials are made.
Updates to all SWEs in the SWE History area are performed.
Topics are reviewed and flagged for updating by the appropriate SME. Changes are made as necessary.
All references are reviewed and updated as necessary.
Updates to other pages are made as necessary including
Tools Table
Acronyms
Terms
PATs
A final review of content is performed before the new SWEHB is released. Releasing consists of IT making the new SWEHB the Home page for Confluence. In that way, the URL "SWEHB.NASA.GOV" will take users to the new Home page. Anonymous users are given only View permission to the new space.
Large Scale Updates and Changes
While minor changes can be made directly in a page, large scale changes that take many days to implement, need a different approach. The full details of the process for making changes is described in the attached PowerPoint presentation SWEHB Branching and Merging.pptx. A brief overview is included below.
SWEHB Branching and Merging
Branch: The page to be changed has a child page added to it where changes will be made and tested.
A full copy of the parent page is made in the child page. The child page is only available to reviewers who have a URL to it.
All changes are made in the tabsetup macro of the child.
Changes may be reviewed by any number of reviewers who have been given the URL to it.
Merge: When changes are deemed acceptable, the entire contents of the tabsetup macro are copied to the parent page. This puts the changes into production and makes them available to everyone.