|
| 1 | +const fs = require('fs') |
| 2 | +const YAML = require('yaml') |
| 3 | + |
| 4 | +const intro = `# Overview |
| 5 | +
|
| 6 | +Standards are the core deliverable of SCS. By standardizing the open source software components of a cloud computing stack, their versions, how they are to be configured, deployed and utilized, SCS guarantees the reproducibility of a certain behavior of this technology. |
| 7 | +
|
| 8 | +SCS standards are discussed, developed and maintained in the community by the corresponding teams (see Track in the table below), which naturally include existing users of SCS.` |
| 9 | +const trackIntros = { |
| 10 | + 'Global': 'This track encompasses the foundational standards that guide the overall structure, documentation, and general topics related to the Sovereign Cloud Stack. It serves as the core framework, ensuring consistency, clarity, and comprehensibility across all aspects of the cloud stack, fostering an environment where information is easily accessible and understood.', |
| 11 | + 'IaaS': 'The IaaS Layer Standards track focuses on the protocols, guidelines, and specifications that govern the infrastructure as a service layer. This encompasses standards for virtual machines, storage, networking, and other foundational resources, ensuring seamless, efficient, and secure operation, interoperability, and management of the underlying cloud infrastructure.', |
| 12 | + 'KaaS': 'Standards in this track are concerned with Kubernetes as a Service layer, outlining norms and best practices for deploying, managing, and operating Kubernetes clusters. These standards aim to ensure that the orchestration of containers is streamlined, secure, and compatible across various cloud environments and platforms.', |
| 13 | + 'IAM': 'This track revolves around Identity and Access Management (IAM) standards, providing guidelines for ensuring secure and efficient user authentication, authorization, and administration. It addresses issues related to user identity, permissions, roles, and policies, aiming to safeguard and streamline access to cloud resources and services.', |
| 14 | + 'Ops': 'Operational Tooling Standards cover the protocols and guidelines associated with tools and utilities used for monitoring, management, and maintenance of the cloud environment. This includes standards for status pages, alerts, logs, and other operational tools, aiming to optimize the reliability, performance, and security of cloud services and resources.', |
| 15 | +} |
| 16 | +const headerLegend = '*Legend to the column headings: Draft, Stable (but not effective), Effective, Deprecated (and no longer effective).' |
| 17 | + |
| 18 | +var filenames = fs |
| 19 | + .readdirSync('standards/') |
| 20 | + .filter((fn) => fn.startsWith('scs-') && fn.endsWith('.md') && !fn.startsWith('scs-X')) |
| 21 | + |
| 22 | +keys = ['title', 'type', 'status', 'track', 'stabilized_at', 'obsoleted_at', 'replaces', 'authors', 'state'] |
| 23 | + |
| 24 | +// use the ISO string, because so do the standard documents, and we can use string comparison with ISO dates |
| 25 | +today = new Date().toISOString().slice(0, 10) |
| 26 | + |
| 27 | +// collect all the information sorted into a track/adr-id/version hierarchy |
| 28 | +tracks = {} |
| 29 | +filenames.forEach((filename) => { |
| 30 | + var components = filename.split('-') |
| 31 | + var obj = { |
| 32 | + ...YAML.parseDocument(fs.readFileSync(`standards/${filename}`, 'utf8')).toJSON(), |
| 33 | + filename, |
| 34 | + id: filename.substring(0, filename.length - 3), |
| 35 | + adrId: components[1], |
| 36 | + version: components[2], |
| 37 | + } |
| 38 | + obj.isStable = obj.stabilized_at !== undefined && obj.stabilized_at <= today |
| 39 | + obj.isObsolete = obj.obsoleted_at !== undefined && obj.obsoleted_at <= today |
| 40 | + obj.isEffective = obj.isStable && !obj.isObsolete |
| 41 | + var track = obj.track |
| 42 | + if (track === undefined) return |
| 43 | + if (tracks[track] === undefined) tracks[track] = {} |
| 44 | + var standards = tracks[track] |
| 45 | + if (standards[obj.adrId] === undefined) standards[obj.adrId] = {versions: []} |
| 46 | + standards[obj.adrId].versions.push(obj) |
| 47 | +}) |
| 48 | + |
| 49 | +function readPrefixLines(fn) { |
| 50 | + var lines = [] |
| 51 | + if (fs.existsSync(fn)) { |
| 52 | + lines = fs.readFileSync(fn, 'utf8').split('\n') |
| 53 | + var tableIdx = lines.findIndex((line) => line.trim().startsWith('|')) |
| 54 | + if (tableIdx >= 0) { |
| 55 | + lines.splice(tableIdx) |
| 56 | + } |
| 57 | + } else console.log(`WARNING: file ${fn} not found`) |
| 58 | + return lines |
| 59 | +} |
| 60 | + |
| 61 | +function mkLinkList(versions) { |
| 62 | + var links = versions.map((v) => `[${v.version}](/standards/${v.id})`) |
| 63 | + return links.join(', ') |
| 64 | +} |
| 65 | + |
| 66 | +// walk down the hierarchy, building adr overview pages, track overview pages, and total overview page |
| 67 | +// as well as the new sidebar |
| 68 | +sidebarItems = [] |
| 69 | +var lines = readPrefixLines('standards/standards/overview.md') |
| 70 | +if (!lines.length) lines.push(`${intro} |
| 71 | +
|
| 72 | +${headerLegend} |
| 73 | +`) |
| 74 | +lines.push('| Standard | Track | Description | Draft | Stable* | Effective | Deprecated* |') |
| 75 | +lines.push('| --------- | ------ | ------------ | ----- | ------- | --------- | ----------- |') |
| 76 | +Object.entries(tracks).forEach((trackEntry) => { |
| 77 | + var track = trackEntry[0] |
| 78 | + var trackPath = `standards/${track.toLowerCase()}` |
| 79 | + fs.mkdirSync(trackPath, { recursive: true }) |
| 80 | + var trackItem = { |
| 81 | + type: 'category', |
| 82 | + label: track, |
| 83 | + link: { |
| 84 | + type: 'doc', |
| 85 | + id: `${track.toLowerCase()}/index`, |
| 86 | + }, |
| 87 | + items: [], |
| 88 | + } |
| 89 | + sidebarItems.push(trackItem) |
| 90 | + var tlines = readPrefixLines(`standards/${track.toLowerCase()}/index.md`) |
| 91 | + if (!tlines.length) { |
| 92 | + tlines.push(`# ${track} Standards |
| 93 | +
|
| 94 | +${trackIntros[track]} |
| 95 | +
|
| 96 | +${headerLegend} |
| 97 | +`) |
| 98 | + } |
| 99 | + tlines.push('| Standard | Description | Draft | Stable* | Effective | Deprecated* |') |
| 100 | + tlines.push('| --------- | ------------ | ----- | ------- | --------- | ----------- |') |
| 101 | + Object.entries(trackEntry[1]).forEach((standardEntry) => { |
| 102 | + var versions = standardEntry[1].versions |
| 103 | + // unfortunately, some standards are obsolete without being stable |
| 104 | + var draftVersions = versions.filter((v) => v.stabilized_at === undefined && v.obsoleted_at === undefined) |
| 105 | + var stableVersions = versions.filter((v) => v.stabilized_at !== undefined && !v.isEffective) |
| 106 | + var effectiveVersions = versions.filter((v) => v.isEffective) |
| 107 | + var deprecatedVersions = versions.filter((v) => v.isObsolete) |
| 108 | + var ref = versions[versions.length - 1] |
| 109 | + if (effectiveVersions.length) { |
| 110 | + ref = effectiveVersions[effectiveVersions.length - 1] |
| 111 | + } |
| 112 | + var adrId = standardEntry[0] |
| 113 | + var standardItem = { |
| 114 | + type: 'category', |
| 115 | + label: `scs-${adrId}`, |
| 116 | + link: { |
| 117 | + type: 'doc', |
| 118 | + id: `${track.toLowerCase()}/scs-${adrId}`, |
| 119 | + }, |
| 120 | + items: [], |
| 121 | + } |
| 122 | + trackItem.items.push(standardItem) |
| 123 | + var slines = readPrefixLines(`standards/${track.toLowerCase()}/scs-${adrId}.md`) |
| 124 | + if (!slines.length) { |
| 125 | + slines.push(`# scs-${adrId}: ${ref.title}\n`) |
| 126 | + if (ref.description !== undefined) { |
| 127 | + slines.push(ref.description) |
| 128 | + } |
| 129 | + } |
| 130 | + slines.push('| Version | Type | State | stabilized | obsoleted |') |
| 131 | + slines.push('| -------- | ----- | ------- | ---------- | --------- |') |
| 132 | + var link = `[scs-${adrId}](/standards/${track.toLowerCase()}/scs-${adrId})` |
| 133 | + var versionList = `${mkLinkList(draftVersions) || '-'} | ${mkLinkList(stableVersions) || '-'} | ${mkLinkList(effectiveVersions) || '-'} | ${mkLinkList(deprecatedVersions) || '-'}` |
| 134 | + lines.push(`| ${link} | ${track} | ${ref.title} | ${versionList} |`) |
| 135 | + tlines.push(`| ${link} | ${ref.title} | ${versionList} |`) |
| 136 | + standardEntry[1].versions.forEach((obj) => { |
| 137 | + var versionItem = { |
| 138 | + type: 'doc', |
| 139 | + label: obj.version.toUpperCase(), |
| 140 | + id: obj.id, |
| 141 | + } |
| 142 | + standardItem.items.push(versionItem) |
| 143 | + slines.push(`| [scs-${adrId}-${obj.version}](/standards/${obj.id}) | ${obj.type} | ${obj.status || obj.state} | ${obj.stabilized_at || '-'} | ${obj.obsoleted_at || '-'} |`) |
| 144 | + }) |
| 145 | + slines.push('') // file should end with a single newline character |
| 146 | + fs.writeFileSync(`${trackPath}/scs-${adrId}.md`, slines.join('\n'), 'utf8') |
| 147 | + }) |
| 148 | + tlines.push('') // file should end with a single newline character |
| 149 | + fs.writeFileSync(`${trackPath}/index.md`, tlines.join('\n'), 'utf8') |
| 150 | +}) |
| 151 | +lines.push('') // file should end with a single newline character |
| 152 | +fs.writeFileSync(`standards/standards/overview.md`, lines.join('\n'), 'utf8') |
| 153 | + |
| 154 | +var newSidebars = `module.exports = ${JSON.stringify(sidebarItems, null, ' ')}` |
| 155 | +fs.writeFileSync('./sidebarsStandardsItems.js', newSidebars, 'utf8') |
0 commit comments