Update generate-docs Action with OCI syntax (#74)

* Update docs with OCI spec changes

* reference to version `:1` than `:latest`

* nit

* sync generate-doc changes

* add workflow condition

* revert features README changes

* address comments

.github/devcontainers-action/action.yml

@@ -24,6 +24,14 @@ inputs:
     required: false
     default: ''
     description: "Relative path to the 'src' folder containing dev container 'feature(s)'"
+  oci-registry:
+    required: false
+    default: "ghcr.io"
+    description: "Name of the OCI registry that implements the OCI Artifact Distribution Specification"
+  features-namespace:
+    required: false
+    default: "<owner>/<repo>"
+    description: "A unique indentifier for the collection of features"
 
   # 'template' options
   base-path-to-templates:

.github/devcontainers-action/dist/index.js

@@ -53,7 +53,7 @@ const FEATURES_README_TEMPLATE = `
 
 \`\`\`json
 "features": {
-        "#{Nwo}/#{Id}@#{VersionTag}": {
+        "#{Registry}/#{Namespace}/#{Id}:#{Version}": {
             "version": "latest"
         }
 }
@@ -76,9 +76,9 @@ const TEMPLATE_README_TEMPLATE = `
 
 #{OptionsTable}
 `;
-function generateFeaturesDocumentation(basePath) {
+function generateFeaturesDocumentation(basePath, ociRegistry, namespace) {
     return __awaiter(this, void 0, void 0, function* () {
-        yield _generateDocumentation(basePath, FEATURES_README_TEMPLATE, 'devcontainer-feature.json');
+        yield _generateDocumentation(basePath, FEATURES_README_TEMPLATE, 'devcontainer-feature.json', ociRegistry, namespace);
     });
 }
 exports.generateFeaturesDocumentation = generateFeaturesDocumentation;
@@ -88,7 +88,7 @@ function generateTemplateDocumentation(basePath) {
     });
 }
 exports.generateTemplateDocumentation = generateTemplateDocumentation;
-function _generateDocumentation(basePath, readmeTemplate, metadataFile) {
+function _generateDocumentation(basePath, readmeTemplate, metadataFile, ociRegistry = '', namespace = '') {
     return __awaiter(this, void 0, void 0, function* () {
         const directories = fs.readdirSync(basePath);
         yield Promise.all(directories.map((f) => __awaiter(this, void 0, void 0, function* () {
@@ -114,13 +114,15 @@ function _generateDocumentation(basePath, readmeTemplate, metadataFile) {
                     return;
                 }
                 const srcInfo = (0, utils_1.getGitHubMetadata)();
-                const ref = srcInfo.ref;
                 const owner = srcInfo.owner;
                 const repo = srcInfo.repo;
-                // Add tag if parseable
-                let versionTag = 'latest';
-                if (ref && ref.includes('refs/tags/')) {
-                    versionTag = ref.replace('refs/tags/', '');
+                // Add version
+                let version = 'latest';
+                const parsedVersion = parsedJson === null || parsedJson === void 0 ? void 0 : parsedJson.version;
+                if (parsedVersion) {
+                    // example - 1.0.0
+                    const splitVersion = parsedVersion.split('.');
+                    version = splitVersion[0];
                 }
                 const generateOptionsMarkdown = () => {
                     const options = parsedJson === null || parsedJson === void 0 ? void 0 : parsedJson.options;
@@ -148,8 +150,9 @@ function _generateDocumentation(basePath, readmeTemplate, metadataFile) {
                     .replace('#{Description}', (_a = parsedJson.description) !== null && _a !== void 0 ? _a : '')
                     .replace('#{OptionsTable}', generateOptionsMarkdown())
                     // Features Only
-                    .replace('#{Nwo}', `${owner}/${repo}`)
-                    .replace('#{VersionTag}', versionTag)
+                    .replace('#{Registry}', ociRegistry)
+                    .replace('#{Namespace}', namespace == '<owner>/<repo>' ? `${owner}/${repo}` : namespace)
+                    .replace('#{Version}', version)
                     // Templates Only
                     .replace('#{ManifestName}', (_c = (_b = parsedJson === null || parsedJson === void 0 ? void 0 : parsedJson.image) === null || _b === void 0 ? void 0 : _b.manifest) !== null && _c !== void 0 ? _c : '')
                     .replace('#{RepoUrl}', urlToConfig);
@@ -232,6 +235,8 @@ function run() {
         };
         const featuresBasePath = core.getInput('base-path-to-features');
         const templatesBasePath = core.getInput('base-path-to-templates');
+        const ociRegistry = core.getInput('oci-registry');
+        const namespace = core.getInput('features-namespace');
         let featuresMetadata = undefined;
         let templatesMetadata = undefined;
         // -- Package Release Artifacts
@@ -246,7 +251,7 @@ function run() {
         // -- Generate Documentation
         if (shouldGenerateDocumentation && featuresBasePath) {
             core.info('Generating documentation for features...');
-            yield (0, generateDocs_1.generateFeaturesDocumentation)(featuresBasePath);
+            yield (0, generateDocs_1.generateFeaturesDocumentation)(featuresBasePath, ociRegistry, namespace);
         }
         if (shouldGenerateDocumentation && templatesBasePath) {
             core.info('Generating documentation for templates...');

.github/devcontainers-action/lib/generateDocs.js

@@ -46,7 +46,7 @@ const FEATURES_README_TEMPLATE = `
 
 \`\`\`json
 "features": {
-        "#{Nwo}/#{Id}@#{VersionTag}": {
+        "#{Registry}/#{Namespace}/#{Id}:#{Version}": {
             "version": "latest"
         }
 }
@@ -69,9 +69,9 @@ const TEMPLATE_README_TEMPLATE = `
 
 #{OptionsTable}
 `;
-function generateFeaturesDocumentation(basePath) {
+function generateFeaturesDocumentation(basePath, ociRegistry, namespace) {
     return __awaiter(this, void 0, void 0, function* () {
-        yield _generateDocumentation(basePath, FEATURES_README_TEMPLATE, 'devcontainer-feature.json');
+        yield _generateDocumentation(basePath, FEATURES_README_TEMPLATE, 'devcontainer-feature.json', ociRegistry, namespace);
     });
 }
 exports.generateFeaturesDocumentation = generateFeaturesDocumentation;
@@ -81,7 +81,7 @@ function generateTemplateDocumentation(basePath) {
     });
 }
 exports.generateTemplateDocumentation = generateTemplateDocumentation;
-function _generateDocumentation(basePath, readmeTemplate, metadataFile) {
+function _generateDocumentation(basePath, readmeTemplate, metadataFile, ociRegistry = '', namespace = '') {
     return __awaiter(this, void 0, void 0, function* () {
         const directories = fs.readdirSync(basePath);
         yield Promise.all(directories.map((f) => __awaiter(this, void 0, void 0, function* () {
@@ -107,13 +107,15 @@ function _generateDocumentation(basePath, readmeTemplate, metadataFile) {
                     return;
                 }
                 const srcInfo = (0, utils_1.getGitHubMetadata)();
-                const ref = srcInfo.ref;
                 const owner = srcInfo.owner;
                 const repo = srcInfo.repo;
-                // Add tag if parseable
-                let versionTag = 'latest';
-                if (ref && ref.includes('refs/tags/')) {
-                    versionTag = ref.replace('refs/tags/', '');
+                // Add version
+                let version = 'latest';
+                const parsedVersion = parsedJson === null || parsedJson === void 0 ? void 0 : parsedJson.version;
+                if (parsedVersion) {
+                    // example - 1.0.0
+                    const splitVersion = parsedVersion.split('.');
+                    version = splitVersion[0];
                 }
                 const generateOptionsMarkdown = () => {
                     const options = parsedJson === null || parsedJson === void 0 ? void 0 : parsedJson.options;
@@ -141,8 +143,9 @@ function _generateDocumentation(basePath, readmeTemplate, metadataFile) {
                     .replace('#{Description}', (_a = parsedJson.description) !== null && _a !== void 0 ? _a : '')
                     .replace('#{OptionsTable}', generateOptionsMarkdown())
                     // Features Only
-                    .replace('#{Nwo}', `${owner}/${repo}`)
-                    .replace('#{VersionTag}', versionTag)
+                    .replace('#{Registry}', ociRegistry)
+                    .replace('#{Namespace}', namespace == '<owner>/<repo>' ? `${owner}/${repo}` : namespace)
+                    .replace('#{Version}', version)
                     // Templates Only
                     .replace('#{ManifestName}', (_c = (_b = parsedJson === null || parsedJson === void 0 ? void 0 : parsedJson.image) === null || _b === void 0 ? void 0 : _b.manifest) !== null && _c !== void 0 ? _c : '')
                     .replace('#{RepoUrl}', urlToConfig);

.github/devcontainers-action/lib/main.js

@@ -59,6 +59,8 @@ function run() {
         };
         const featuresBasePath = core.getInput('base-path-to-features');
         const templatesBasePath = core.getInput('base-path-to-templates');
+        const ociRegistry = core.getInput('oci-registry');
+        const namespace = core.getInput('features-namespace');
         let featuresMetadata = undefined;
         let templatesMetadata = undefined;
         // -- Package Release Artifacts
@@ -73,7 +75,7 @@ function run() {
         // -- Generate Documentation
         if (shouldGenerateDocumentation && featuresBasePath) {
             core.info('Generating documentation for features...');
-            yield (0, generateDocs_1.generateFeaturesDocumentation)(featuresBasePath);
+            yield (0, generateDocs_1.generateFeaturesDocumentation)(featuresBasePath, ociRegistry, namespace);
         }
         if (shouldGenerateDocumentation && templatesBasePath) {
             core.info('Generating documentation for templates...');

.github/workflows/update-documentation.yml

@@ -8,7 +8,7 @@ on:
 jobs:
   generate:
     runs-on: ubuntu-latest
-    if: "!contains(github.event.head_commit.message, 'no-ci') && !contains(github.event.head_commit.message, 'CI ignore')"
+    if: "github.ref == 'refs/heads/main' && !contains(github.event.head_commit.message, 'no-ci') && !contains(github.event.head_commit.message, 'CI ignore')"
     steps:
       - uses: actions/checkout@v2
 

README.md

@@ -67,21 +67,21 @@ See the relevant feature's README for supported options.
 "name": "my-project-devcontainer",
 "image": "mcr.microsoft.com/devcontainers/base:ubuntu",  // Any generic, debian-based image.
 features: {
-    "devcontainers/features/go@latest": {
+    "ghcr.io/devcontainers/features/go:1": {
         "version": "1.18"
     },
-    "devcontainers/features/docker-in-docker@latest": {
+    "ghcr.io/devcontainers/features/docker-in-docker:1": {
         "version": "latest",
         "moby": true
     }
 }
 ```
 
-The `@latest` version annotation is added implicitly if omitted. To pin to a specific [release tag](https://github.com/devcontainers/features/releases), append it to the end of the feature.
+The `:latest` version annotation is added implicitly if omitted. To pin to a specific package version ([example](https://github.com/devcontainers/features/pkgs/container/features/go/versions)), append it to the end of the feature.
 
 ```jsonc
 features: {
-    "devcontainers/features/go@v0.0.2": {
+    "ghcr.io/devcontainers/features/go:1": {
         "version": "1.18"
     },
 ```