From 8101678b4d3671ac54f5d487b88d0d1f4b704230 Mon Sep 17 00:00:00 2001 From: Natalia Luzuriaga Date: Thu, 21 Aug 2025 09:18:04 -0700 Subject: [PATCH 1/2] Updated procedures doc Signed-off-by: Natalia Luzuriaga --- docs/procedures.md | 40 ++++++++++++++++++++++++++++++---------- 1 file changed, 30 insertions(+), 10 deletions(-) diff --git a/docs/procedures.md b/docs/procedures.md index 0968f76..6a9f786 100644 --- a/docs/procedures.md +++ b/docs/procedures.md @@ -4,25 +4,28 @@ The CMS Open Source Program Office developed various tools that can automate det > **Learn more about our SHARE IT Act tools**: https://dsacms.github.io/share-it-act-lp/ -## Creating a code.json file +**Procedures for Project Teams**: +[Creating a code.json file in your repository](#creating-a-codejson-file-in-your-repository) +- [code.json generator form site](#using-form-site) +- [automated-codejson-generator GitHub Action](#using-automated-codejson-generator) +- [repo-scaffolder](#using-repo-scaffolder) -### Using repo-scaffolder - -[repo-scaffolder](https://github.com/DSACMS/repo-scaffolder) is a tool for creating repositories that adhere to repository hygiene standards. It provides file templates detailing project information, contributing guidance, maintainer roles, community involvement, and **project metadata**. +***Procedures for Agencies**: +[Generate an agency-index.json file for submission](#generate-an-agency-indexjson-file-for-agencies) +- [codejson-index-generator](#using-codejson-index-generator) -For repositories created using repo-scaffolder, the tool can assist with adding code.json to the repository. Navigate to your project's `.github` directory and run the following cookiecutter command. You will be asked questions about the project in order to collect and store this metadata in code.json. -``` -cookiecutter . --directory=codejson -``` - -For more information on repo-scaffolder, check out the [documentation](https://github.com/DSACMS/repo-scaffolder?tab=readme-ov-file#metadata-collection-using-codejson). +## Creating a code.json file in your repository ### Using form site +*This method works best for all repositories on all platforms.* Users can fill out a web form that creates a code.json file to be uploaded to a project's source code repository: https://dsacms.github.io/codejson-generator. + + ### Using automated-codejson-generator +*This method works best for repositories hosted on GitHub with GitHub Actions enabled.* The [automated-codejson-generator](https://github.com/DSACMS/automated-codejson-generator) is a GitHub Action that automatically generates and maintains code.json files for federal open source repositories. It ensures schema consistency and automates metadata calculations, including: @@ -31,6 +34,19 @@ The [automated-codejson-generator](https://github.com/DSACMS/automated-codejson- - Repository information - Timestamps +### Using repo-scaffolder +*This method is most effective when GitHub Actions are unavailable, allowing cookiecutter to be installed locally with Python.* + +[repo-scaffolder](https://github.com/DSACMS/repo-scaffolder) is a tool for creating repositories that adhere to repository hygiene standards. It provides file templates detailing project information, contributing guidance, maintainer roles, community involvement, and **project metadata**. + +For repositories created using repo-scaffolder, the tool can assist with adding code.json to the repository. Navigate to your project's `.github` directory and run the following cookiecutter command. You will be asked questions about the project in order to collect and store this metadata in code.json. + +``` +cookiecutter . --directory=codejson +``` + +For more information on repo-scaffolder, check out the [documentation](https://github.com/DSACMS/repo-scaffolder?tab=readme-ov-file#metadata-collection-using-codejson). + #### Setting up the GitHub Action To use the automated-codejson-generator in your repository, create a workflow file with the following configuration: @@ -74,10 +90,14 @@ jobs: This action will create a pull request to add or update a compliant code.json file in your repository. +## Generate an agency-index.json file for agencies + ### Using codejson-index-generator The [codejson-index-generator](https://github.com/DSACMS/codejson-index-generator) is a Python-based tool that helps federal agencies compile and maintain their code.json files for code.gov compliance. It scans specified GitHub organizations, finds repositories containing code.json files, and combines them into a single indexed file. +The tool can be run using the [index-generator-website](https://dsacms.github.io/index-generator-website/).Alternatively, follow the instructions below to run locally. + #### Prerequisites - Python 3.x From f04d61e7ea2cee2ed2bc26dfdb0bc47b756cbaf4 Mon Sep 17 00:00:00 2001 From: Natalia Luzuriaga Date: Thu, 21 Aug 2025 09:22:22 -0700 Subject: [PATCH 2/2] Changed formatting Signed-off-by: Natalia Luzuriaga --- docs/procedures.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/procedures.md b/docs/procedures.md index 6a9f786..1ec57b9 100644 --- a/docs/procedures.md +++ b/docs/procedures.md @@ -96,7 +96,9 @@ This action will create a pull request to add or update a compliant code.json fi The [codejson-index-generator](https://github.com/DSACMS/codejson-index-generator) is a Python-based tool that helps federal agencies compile and maintain their code.json files for code.gov compliance. It scans specified GitHub organizations, finds repositories containing code.json files, and combines them into a single indexed file. -The tool can be run using the [index-generator-website](https://dsacms.github.io/index-generator-website/).Alternatively, follow the instructions below to run locally. +The tool can be run using the [index-generator-website](https://dsacms.github.io/index-generator-website/). + +Alternatively, follow the instructions below to run locally. #### Prerequisites