From a5077d319d358f7c21ba2bc574fd23dd4c341f30 Mon Sep 17 00:00:00 2001 From: David Harris Date: Mon, 12 Feb 2024 14:38:54 -0500 Subject: [PATCH 01/16] Update skeleton instructions for README This commit will remove out-dated skeleton tool instructions. Previously the documentation was using a legacy skeleton tool. Now the instructions will reflect using the gh CLI skeleton tool extension. Links have been updated along with steps to make a repository from a skeleton. --- project_setup/README.md | 34 +++++++-------- project_setup/skeleton-list.md | 16 ++++---- .../skeletonize-existing-repository.md | 41 ++++++++++--------- 3 files changed, 48 insertions(+), 43 deletions(-) diff --git a/project_setup/README.md b/project_setup/README.md index c9eb6a8..3c6dd6c 100644 --- a/project_setup/README.md +++ b/project_setup/README.md @@ -3,10 +3,11 @@ We recommend you follow the directions below and use a skeleton for all new repositories. -The [`skeleton`](scripts/skeleton) -helper tool included in the [`scripts`](scripts) directory can quickly setup -a new local repository. Once you've cloned and configured the repository -to your local machine, it can be published to a repository created on GitHub. +The [`gh CLI extension`](https://github.com/cisagov/gh-skeleton) +tool provides the ability to easily start new projects from the +existing library of skeleton repositories. Once you've cloned +and configured the repository to your local machine, it can +be published to a repository created on GitHub. For repositories created from skeletons, run `setup-env` and `pre-commit install` to [set up your environment](#set-up-your-environment-and-pre-commit), @@ -19,7 +20,7 @@ branch protection - [see our branch protection guide for details](branch-protect ## Contents ## - [Adding a skeleton configuration to an existing repository](#adding-a-skeleton-configuration-to-an-existing-repository) -- [Using the skeleton tool to start a new repository ๐Ÿ’€๐Ÿ› ](#using-the-skeleton-tool-to-start-a-new-repository-) +- [Using the gh CLI extension tool to start a new repository ๐Ÿ’€๐Ÿ› ](#using-the-gh-cli-extension-tool-to-start-a-new-repository-) - [Selecting a skeleton](#selecting-a-skeleton) - [Cloning a selected skeleton](#cloning-a-selected-skeleton) - [Create and publish the GitHub repository](#create-and-publish-the-github-repository) @@ -38,14 +39,15 @@ branch protection - [see our branch protection guide for details](branch-protect To skeletonize an existing repository, please see the guide to [skeletonize an existing repository](skeletonize-existing-repository.md). -## Using the skeleton tool to start a new repository ๐Ÿ’€๐Ÿ›  ## +## Using the gh CLI extension tool to start a new repository ๐Ÿ’€๐Ÿ›  ## We recommend that you start your project from one of the [skeleton projects](https://github.com/search?q=org%3Acisagov+topic%3Askeleton) -in this organization. The [`skeleton`](scripts/skeleton) -helper tool included in the [`scripts`](scripts) directory can quickly setup -a new local repository. Once you've cloned and configured the repository -to your local machine, you then publish it to a repository created on GitHub. +in this organization. The [`gh CLI`](https://github.com/cisagov/gh-skeleton) +extension provides the ability to easily start new projects from the existing +library of skeleton repositories. Once you've cloned and configured the +repository to your local machine, you then publish it to a repository +created on GitHub. ### Selecting a skeleton ### @@ -54,7 +56,7 @@ for your new repository. For a list of available skeletons, see the [Skeleton List](skeleton-list.md) or use the following command: ```bash -./skeleton list +gh skeleton list ``` ```console @@ -87,19 +89,19 @@ skeleton-aws-lambda ### Cloning a selected skeleton ### -Next, use the `skeleton` tool to clone, rename, and prepare the contents of +Next, use the `git` tool to clone, rename, and prepare the contents of your new repository for publication. The tool will print out each command it is issuing and its result. ```console -./skeleton clone [options] +git clone [options] ``` For example, to create a project based on `skeleton-ansible-role` named `ansible-role-quantum-rng` in your local `~/projects` directory: ```bash -./skeleton clone --change-dir ~/projects skeleton-ansible-role ansible-role-quantum-rng +git clone --change-dir ~/projects skeleton-ansible-role ansible-role-quantum-rng ``` This command results in: @@ -145,7 +147,7 @@ Use the following commands to push the new repository to github: ## Create and publish the GitHub repository ## -Once the `skeleton` tool has run, the next step is to publish to a GitHub +Once the `gh CLI extension` tool has run, the next step is to publish to a GitHub remote repository. To publish your new repository on GitHub, the remote must already exist. @@ -165,7 +167,7 @@ git push --set-upstream origin develop ## Disabling squash merging ## Click on the settings tab for your new repository and, in the -"Options" section, make sure that "Allow squash merging" is +"Pull Request" section, make sure that "Allow squash merging" is *unchecked*. ## Set up your environment and pre-commit ## diff --git a/project_setup/skeleton-list.md b/project_setup/skeleton-list.md index 82dcd3d..45c63d5 100644 --- a/project_setup/skeleton-list.md +++ b/project_setup/skeleton-list.md @@ -4,23 +4,23 @@ We maintain a number of [`cisagov` skeleton projects](https://github.com/search? to make starting new repositories quicker and to simplify maintaining configurations and dependencies across the organization. -The [`skeleton`](scripts/skeleton) helper tool is included in the [`scripts`](scripts) -directory of the [development-guide](https://github.com/cisagov/development-guide) -repository. +The [`gh CLI`](https://github.com/cisagov/gh-skeleton) extension tool +provides the ability to easily start new projects from existing +library of skeleton repositories. - To skeletonize an existing repository, please see the guide to [skeletonize an existing repository](skeletonize-existing-repository.md). - To skeletonize a new repository, please see the guide to -[start a new repository from a skeleton](new-repository-from-skeleton.md). +[start a new repository from a skeleton](https://github.com/cisagov/gh-skeleton). ## List available skeletons with the command-line tool ## -After you've run `setup-env` in this repository, the `skeleton` tool will be -available to you via the command line. To see a list of available skeletons, -use the following command: +After you've run `setup-env` in this repository, the `gh CLI extension` +tool will be available to you via the command line. To see a list of +available skeletons, use the following command: ```bash -skeleton list +gh skeleton list ``` ## Available skeletons in cisagov ## diff --git a/project_setup/skeletonize-existing-repository.md b/project_setup/skeletonize-existing-repository.md index 7078281..ce8a896 100644 --- a/project_setup/skeletonize-existing-repository.md +++ b/project_setup/skeletonize-existing-repository.md @@ -1,12 +1,14 @@ # Skeletonize an Existing Repository # Skeletonizing a repository standardizes our development setup and environment, -and it enables our [Lineage GitHub Action](https://github.com/cisagov/action-lineage/) -to keep the repository updated and standardized. +and enables our [Lineage GitHub Action](https://github.com/cisagov/action-lineage/) +to keep the repository updated and standardized. The purpose of the +instruction here is to skeletonize an existing non-skeletonized +repository. ## About ## -Skeleton projects contain [licensing information](LICENSE), as +Skeleton projects contain [licensing information](../LICENSE), as well as [pre-commit hooks](https://pre-commit.com) and [GitHub Actions](https://github.com/features/actions) configurations appropriate for the major languages that we use. This lets us standardize @@ -15,12 +17,12 @@ appropriate for the major languages that we use. This lets us standardize ## General overview ## -The general outline of how to add a skeleton to a repository is: +The general outline of how to add a skeleton to an existing repository is: -1. [Add the skeleton as a remote](#add-a-skeleton-as-remote) to the -non-skeletonized repository +1. [Add the skeleton as a remote](#add-the-skeleton-as-a-remote) to the +non-skeletonized existing repository 1. Pull with `--allow-unrelated-histories` -1. [Fix all the inevitable conflicts](#fix-merge-conflicts) +1. [Fix all the inevitable merge conflicts](#fix-all-the-inevitable-merge-conflicts) 1. [Review non-conflicting changes](#review-non-conflicting-changes) to prevent merging destructive upstream changes 1. [Update skeleton's `example` references](#update-skeletons-example-references) @@ -28,10 +30,11 @@ prevent merging destructive upstream changes 1. Fix additional problems that may arise 1. [Make a pull request](#make-a-pull-request) -## Add a skeleton as remote ## +## Add the skeleton as a remote ## -First, decide which of the available skeletons fits your existing repository. -To see a list of available skeletons, use the `skeleton list` command or see +First, decide which of the available skeletons best fits your +existing non-skeletonized repository. To see a list of available +skeletons, use the `gh skeleton list` command or see the [list of skeletons](skeleton-list.md). As an example, we'll be using [`skeleton-python-library`](https://github.com/cisagov/skeleton-python-library) @@ -63,10 +66,10 @@ up the prerequisites, this involves: pre-commit install ``` -## Fix merge conflicts ## +## Fix all the inevitable merge conflicts ## -This merge process will almost certainly fail, resulting in merge conflicts. -The next step is to fix those conflicts and add the files once the fixes are +The merge process will almost certainly fail, resulting in merge conflicts. +The next step is to fix the conflicts and add the files once the fixes are in place. ```sh @@ -98,21 +101,21 @@ from merging in destructive upstream changes. ## Update skeleton's `example` references ## +Some skeletons need additional configuration. For example, with +`skeleton-python-library` and its module structure inside `src/example`. + This step includes such activities as: - Update `setup.py` with non-example information - Arrange into appropriate folders, such as `src` and `test` -- Update the `codeowners` to reflect subject matter expertise and +- Update the `codeowners` file to reflect subject matter expertise and codebase familiarity - Aim to have at least two codeowners for every repository -Some skeletons need additional configuration, such as with -`skeleton-python-library` and its module structure inside `src/example`. - ## Run pre-commit against existing files ## The skeleton will bring along with it our standard pre-commit hook -configurations, including linting and other checks, with `setup-env`. +configurations, including linting and other checks, within `setup-env`. ```sh # Check all existing files @@ -150,7 +153,7 @@ repository still passes its test suite. ## Make a pull request ## -Once you've run through the configuration and testing stages, you've probably +Once you've completed the configuration and testing stages, you've probably accumulated a number of commits on your `skeletonize` branch. The next step is to [make a pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request) From 950785e6b65d063935c48638f8c9b51f82d5884e Mon Sep 17 00:00:00 2001 From: David Harris Date: Tue, 13 Feb 2024 14:29:58 -0500 Subject: [PATCH 02/16] Add description change for gh skeleton tool Updated naming of gh tool to be more accurate verbiage from gh CLI extension to gh skeleton. Updated link to skeleton AWS lambda python which was linked to archived skeleton AWS lambda. --- project_setup/README.md | 31 ++++++++++++++----------------- project_setup/skeleton-list.md | 13 +++++++------ 2 files changed, 21 insertions(+), 23 deletions(-) diff --git a/project_setup/README.md b/project_setup/README.md index 3c6dd6c..121c45b 100644 --- a/project_setup/README.md +++ b/project_setup/README.md @@ -3,11 +3,9 @@ We recommend you follow the directions below and use a skeleton for all new repositories. -The [`gh CLI extension`](https://github.com/cisagov/gh-skeleton) +The [`gh-skeleton`](https://github.com/cisagov/gh-skeleton) tool provides the ability to easily start new projects from the -existing library of skeleton repositories. Once you've cloned -and configured the repository to your local machine, it can -be published to a repository created on GitHub. +existing library of skeleton repositories. For repositories created from skeletons, run `setup-env` and `pre-commit install` to [set up your environment](#set-up-your-environment-and-pre-commit), @@ -20,7 +18,7 @@ branch protection - [see our branch protection guide for details](branch-protect ## Contents ## - [Adding a skeleton configuration to an existing repository](#adding-a-skeleton-configuration-to-an-existing-repository) -- [Using the gh CLI extension tool to start a new repository ๐Ÿ’€๐Ÿ› ](#using-the-gh-cli-extension-tool-to-start-a-new-repository-) +- [Using the gh-skeleton tool to start a new repository ๐Ÿ’€๐Ÿ› ](#using-the-gh-skeleton-tool-to-start-a-new-repository-) - [Selecting a skeleton](#selecting-a-skeleton) - [Cloning a selected skeleton](#cloning-a-selected-skeleton) - [Create and publish the GitHub repository](#create-and-publish-the-github-repository) @@ -39,15 +37,13 @@ branch protection - [see our branch protection guide for details](branch-protect To skeletonize an existing repository, please see the guide to [skeletonize an existing repository](skeletonize-existing-repository.md). -## Using the gh CLI extension tool to start a new repository ๐Ÿ’€๐Ÿ›  ## +## Using the gh-skeleton tool to start a new repository ๐Ÿ’€๐Ÿ›  ## We recommend that you start your project from one of the [skeleton projects](https://github.com/search?q=org%3Acisagov+topic%3Askeleton) -in this organization. The [`gh CLI`](https://github.com/cisagov/gh-skeleton) -extension provides the ability to easily start new projects from the existing -library of skeleton repositories. Once you've cloned and configured the -repository to your local machine, you then publish it to a repository -created on GitHub. +in this organization. The [`gh-skeleton`](https://github.com/cisagov/gh-skeleton) +tool provides the ability to easily start new projects from the existing +library of skeleton repositories. ### Selecting a skeleton ### @@ -89,19 +85,20 @@ skeleton-aws-lambda ### Cloning a selected skeleton ### -Next, use the `git` tool to clone, rename, and prepare the contents of -your new repository for publication. The tool will print out each command it -is issuing and its result. +Next, use the [`gh-skeleton`](https://github.com/cisagov/gh-skeleton) +tool to clone, rename, and prepare the contents of your new repository +for publication. The tool will print out each command it is issuing +and its result. ```console -git clone [options] +gh skeleton clone [options] ``` For example, to create a project based on `skeleton-ansible-role` named `ansible-role-quantum-rng` in your local `~/projects` directory: ```bash -git clone --change-dir ~/projects skeleton-ansible-role ansible-role-quantum-rng +gh skeleton clone --change-dir ~/projects skeleton-ansible-role ansible-role-quantum-rng ``` This command results in: @@ -147,7 +144,7 @@ Use the following commands to push the new repository to github: ## Create and publish the GitHub repository ## -Once the `gh CLI extension` tool has run, the next step is to publish to a GitHub +Once the `gh-skeleton` tool has run, the next step is to publish to a GitHub remote repository. To publish your new repository on GitHub, the remote must already exist. diff --git a/project_setup/skeleton-list.md b/project_setup/skeleton-list.md index 45c63d5..f1c9a9f 100644 --- a/project_setup/skeleton-list.md +++ b/project_setup/skeleton-list.md @@ -4,9 +4,9 @@ We maintain a number of [`cisagov` skeleton projects](https://github.com/search? to make starting new repositories quicker and to simplify maintaining configurations and dependencies across the organization. -The [`gh CLI`](https://github.com/cisagov/gh-skeleton) extension tool -provides the ability to easily start new projects from existing -library of skeleton repositories. +The [`gh-skeleton`](https://github.com/cisagov/gh-skeleton) is +a custom tool that provides the ability to easily start new projects +from existing library of skeleton repositories. - To skeletonize an existing repository, please see the guide to [skeletonize an existing repository](skeletonize-existing-repository.md). @@ -15,8 +15,9 @@ library of skeleton repositories. ## List available skeletons with the command-line tool ## -After you've run `setup-env` in this repository, the `gh CLI extension` -tool will be available to you via the command line. To see a list of +After you've installed the [`gh` CLI](https://github.com/cli/cli) followed +by the [`gh-skeleton`](https://github.com/cisagov/gh-skeleton) extension, +the tool will be available to you via the command line. To see a list of available skeletons, use the following command: ```bash @@ -47,7 +48,7 @@ that role requires an AWS test user. [`skeleton-packer`](https://github.com/cisagov/skeleton-packer): A skeleton project for quickly getting a new cisagov packer project started. -[`skeleton-aws-lambda`](https://github.com/cisagov/skeleton-aws-lambda): +[`skeleton-aws-lambda-python`](https://github.com/cisagov/skeleton-aws-lambda-python): A skeleton project for quickly getting a new cisagov Python AWS Lambda started. Note: If you discover a new flavor of skeleton that doesn't yet exist, use From 9c69ff6d2f8cd182d988207cd8cded829913836c Mon Sep 17 00:00:00 2001 From: David Harris <123905168+dv4harr10@users.noreply.github.com> Date: Thu, 15 Feb 2024 10:31:11 -0500 Subject: [PATCH 03/16] Apply suggestions from code review Update naming convention to GitHub CLI 'gh' Extension Co-authored-by: Shane Frasier --- project_setup/README.md | 12 ++++++------ project_setup/skeleton-list.md | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/project_setup/README.md b/project_setup/README.md index 121c45b..888ca01 100644 --- a/project_setup/README.md +++ b/project_setup/README.md @@ -4,7 +4,7 @@ We recommend you follow the directions below and use a skeleton for all new repositories. The [`gh-skeleton`](https://github.com/cisagov/gh-skeleton) -tool provides the ability to easily start new projects from the +GitHub CLI (`gh`) extension provides the ability to easily start new projects from the existing library of skeleton repositories. For repositories created from skeletons, run `setup-env` and @@ -18,7 +18,7 @@ branch protection - [see our branch protection guide for details](branch-protect ## Contents ## - [Adding a skeleton configuration to an existing repository](#adding-a-skeleton-configuration-to-an-existing-repository) -- [Using the gh-skeleton tool to start a new repository ๐Ÿ’€๐Ÿ› ](#using-the-gh-skeleton-tool-to-start-a-new-repository-) +- [Using the gh-skeleton `gh` extension to start a new repository ๐Ÿ’€๐Ÿ› ](#using-the-gh-skeleton-gh-extension-to-start-a-new-repository-) - [Selecting a skeleton](#selecting-a-skeleton) - [Cloning a selected skeleton](#cloning-a-selected-skeleton) - [Create and publish the GitHub repository](#create-and-publish-the-github-repository) @@ -37,12 +37,12 @@ branch protection - [see our branch protection guide for details](branch-protect To skeletonize an existing repository, please see the guide to [skeletonize an existing repository](skeletonize-existing-repository.md). -## Using the gh-skeleton tool to start a new repository ๐Ÿ’€๐Ÿ›  ## +## Using the gh-skeleton `gh` extension to start a new repository ๐Ÿ’€๐Ÿ›  ## We recommend that you start your project from one of the [skeleton projects](https://github.com/search?q=org%3Acisagov+topic%3Askeleton) in this organization. The [`gh-skeleton`](https://github.com/cisagov/gh-skeleton) -tool provides the ability to easily start new projects from the existing +`gh` extension provides the ability to easily start new projects from the existing library of skeleton repositories. ### Selecting a skeleton ### @@ -86,7 +86,7 @@ skeleton-aws-lambda ### Cloning a selected skeleton ### Next, use the [`gh-skeleton`](https://github.com/cisagov/gh-skeleton) -tool to clone, rename, and prepare the contents of your new repository +`gh` extension to clone, rename, and prepare the contents of your new repository for publication. The tool will print out each command it is issuing and its result. @@ -144,7 +144,7 @@ Use the following commands to push the new repository to github: ## Create and publish the GitHub repository ## -Once the `gh-skeleton` tool has run, the next step is to publish to a GitHub +Once the `gh-skeleton` `gh` extension has run, the next step is to publish to a GitHub remote repository. To publish your new repository on GitHub, the remote must already exist. diff --git a/project_setup/skeleton-list.md b/project_setup/skeleton-list.md index f1c9a9f..34d84da 100644 --- a/project_setup/skeleton-list.md +++ b/project_setup/skeleton-list.md @@ -5,7 +5,7 @@ to make starting new repositories quicker and to simplify maintaining configurations and dependencies across the organization. The [`gh-skeleton`](https://github.com/cisagov/gh-skeleton) is -a custom tool that provides the ability to easily start new projects +a GitHub CLI (`gh`) extension that provides the ability to easily start new projects from existing library of skeleton repositories. - To skeletonize an existing repository, please see the guide to From 5303b7a0623540cb3bd3a10bbfaa50f49643ab46 Mon Sep 17 00:00:00 2001 From: David Harris <123905168+dv4harr10@users.noreply.github.com> Date: Thu, 15 Feb 2024 10:38:01 -0500 Subject: [PATCH 04/16] Link Correction Co-authored-by: Shane Frasier --- project_setup/skeleton-list.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/project_setup/skeleton-list.md b/project_setup/skeleton-list.md index 34d84da..a87265b 100644 --- a/project_setup/skeleton-list.md +++ b/project_setup/skeleton-list.md @@ -11,7 +11,7 @@ from existing library of skeleton repositories. - To skeletonize an existing repository, please see the guide to [skeletonize an existing repository](skeletonize-existing-repository.md). - To skeletonize a new repository, please see the guide to -[start a new repository from a skeleton](https://github.com/cisagov/gh-skeleton). +[start a new repository from a skeleton](README.md). ## List available skeletons with the command-line tool ## From 6a5c4cb754587619c0ee5798f71a292818eb610f Mon Sep 17 00:00:00 2001 From: David Harris <123905168+dv4harr10@users.noreply.github.com> Date: Thu, 15 Feb 2024 10:40:04 -0500 Subject: [PATCH 05/16] Language verbiage corrections Co-authored-by: Shane Frasier --- project_setup/skeletonize-existing-repository.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/project_setup/skeletonize-existing-repository.md b/project_setup/skeletonize-existing-repository.md index ce8a896..ac329f9 100644 --- a/project_setup/skeletonize-existing-repository.md +++ b/project_setup/skeletonize-existing-repository.md @@ -3,7 +3,7 @@ Skeletonizing a repository standardizes our development setup and environment, and enables our [Lineage GitHub Action](https://github.com/cisagov/action-lineage/) to keep the repository updated and standardized. The purpose of the -instruction here is to skeletonize an existing non-skeletonized +instructions here is to describe how to skeletonize an existing non-skeletonized repository. ## About ## @@ -20,7 +20,7 @@ appropriate for the major languages that we use. This lets us standardize The general outline of how to add a skeleton to an existing repository is: 1. [Add the skeleton as a remote](#add-the-skeleton-as-a-remote) to the -non-skeletonized existing repository +existing non-skeletonized repository 1. Pull with `--allow-unrelated-histories` 1. [Fix all the inevitable merge conflicts](#fix-all-the-inevitable-merge-conflicts) 1. [Review non-conflicting changes](#review-non-conflicting-changes) to @@ -115,7 +115,7 @@ codebase familiarity ## Run pre-commit against existing files ## The skeleton will bring along with it our standard pre-commit hook -configurations, including linting and other checks, within `setup-env`. +configurations, including linting and other checks, with `setup-env`. ```sh # Check all existing files From 9e86d9f009525df84c75d4e37c5a282d29b50df9 Mon Sep 17 00:00:00 2001 From: Jeremy Frasier Date: Thu, 15 Feb 2024 13:23:27 -0500 Subject: [PATCH 06/16] Reformat to placate Markdown linter --- project_setup/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/project_setup/README.md b/project_setup/README.md index 888ca01..4ad8774 100644 --- a/project_setup/README.md +++ b/project_setup/README.md @@ -3,9 +3,9 @@ We recommend you follow the directions below and use a skeleton for all new repositories. -The [`gh-skeleton`](https://github.com/cisagov/gh-skeleton) -GitHub CLI (`gh`) extension provides the ability to easily start new projects from the -existing library of skeleton repositories. +The [`gh-skeleton`](https://github.com/cisagov/gh-skeleton) GitHub CLI +(`gh`) extension provides the ability to easily start new projects +from the existing library of skeleton repositories. For repositories created from skeletons, run `setup-env` and `pre-commit install` to [set up your environment](#set-up-your-environment-and-pre-commit), From bb058e7079b7c7b527e11682e05e3c0da48491f9 Mon Sep 17 00:00:00 2001 From: David Harris Date: Thu, 15 Feb 2024 16:11:10 -0500 Subject: [PATCH 07/16] Fix text and link for merge conflict --- project_setup/skeletonize-existing-repository.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/project_setup/skeletonize-existing-repository.md b/project_setup/skeletonize-existing-repository.md index ac329f9..d2ac6d4 100644 --- a/project_setup/skeletonize-existing-repository.md +++ b/project_setup/skeletonize-existing-repository.md @@ -22,7 +22,7 @@ The general outline of how to add a skeleton to an existing repository is: 1. [Add the skeleton as a remote](#add-the-skeleton-as-a-remote) to the existing non-skeletonized repository 1. Pull with `--allow-unrelated-histories` -1. [Fix all the inevitable merge conflicts](#fix-all-the-inevitable-merge-conflicts) +1. [Fix merge conflicts](#fix-merge-conflicts) 1. [Review non-conflicting changes](#review-non-conflicting-changes) to prevent merging destructive upstream changes 1. [Update skeleton's `example` references](#update-skeletons-example-references) @@ -66,7 +66,7 @@ up the prerequisites, this involves: pre-commit install ``` -## Fix all the inevitable merge conflicts ## +## Fix merge conflicts ## The merge process will almost certainly fail, resulting in merge conflicts. The next step is to fix the conflicts and add the files once the fixes are From f5425f3e698cb96447a66bbb4fa9282cd1621656 Mon Sep 17 00:00:00 2001 From: David Harris Date: Wed, 28 Feb 2024 09:47:09 -0500 Subject: [PATCH 08/16] Suggested text changes from code review This commit updates Development guide Readme and Skeletonize existing repository according to requested changes for wording, grammar, replacing text and delete emoji. --- project_setup/README.md | 14 +++++++------- project_setup/skeletonize-existing-repository.md | 8 ++++---- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/project_setup/README.md b/project_setup/README.md index 4ad8774..d479d32 100644 --- a/project_setup/README.md +++ b/project_setup/README.md @@ -18,7 +18,7 @@ branch protection - [see our branch protection guide for details](branch-protect ## Contents ## - [Adding a skeleton configuration to an existing repository](#adding-a-skeleton-configuration-to-an-existing-repository) -- [Using the gh-skeleton `gh` extension to start a new repository ๐Ÿ’€๐Ÿ› ](#using-the-gh-skeleton-gh-extension-to-start-a-new-repository-) +- [Using the gh-skeleton `gh` extension to start a new repository](#using-the-gh-skeleton-gh-extension-to-start-a-new-repository-) - [Selecting a skeleton](#selecting-a-skeleton) - [Cloning a selected skeleton](#cloning-a-selected-skeleton) - [Create and publish the GitHub repository](#create-and-publish-the-github-repository) @@ -51,11 +51,11 @@ First, identify a suitable skeleton project to use as the starting point for your new repository. For a list of available skeletons, see the [Skeleton List](skeleton-list.md) or use the following command: -```bash -gh skeleton list -``` - ```console +$ gh skeleton list + + + Available skeletons in cisagov: skeleton-python-library @@ -91,13 +91,13 @@ for publication. The tool will print out each command it is issuing and its result. ```console -gh skeleton clone [options] +$ gh skeleton clone [options] ``` For example, to create a project based on `skeleton-ansible-role` named `ansible-role-quantum-rng` in your local `~/projects` directory: -```bash +```console gh skeleton clone --change-dir ~/projects skeleton-ansible-role ansible-role-quantum-rng ``` diff --git a/project_setup/skeletonize-existing-repository.md b/project_setup/skeletonize-existing-repository.md index d2ac6d4..94a738f 100644 --- a/project_setup/skeletonize-existing-repository.md +++ b/project_setup/skeletonize-existing-repository.md @@ -1,9 +1,9 @@ # Skeletonize an Existing Repository # -Skeletonizing a repository standardizes our development setup and environment, +Skeletonizing a repository standardizes our development setup and environment and enables our [Lineage GitHub Action](https://github.com/cisagov/action-lineage/) to keep the repository updated and standardized. The purpose of the -instructions here is to describe how to skeletonize an existing non-skeletonized +instructions here are to describe how to skeletonize an existing non-skeletonized repository. ## About ## @@ -21,7 +21,7 @@ The general outline of how to add a skeleton to an existing repository is: 1. [Add the skeleton as a remote](#add-the-skeleton-as-a-remote) to the existing non-skeletonized repository -1. Pull with `--allow-unrelated-histories` +1. Pull with `git pull--allow-unrelated-histories skeleton parent` 1. [Fix merge conflicts](#fix-merge-conflicts) 1. [Review non-conflicting changes](#review-non-conflicting-changes) to prevent merging destructive upstream changes @@ -108,7 +108,7 @@ This step includes such activities as: - Update `setup.py` with non-example information - Arrange into appropriate folders, such as `src` and `test` -- Update the `codeowners` file to reflect subject matter expertise and +- Update the `.github/CODEOWNERS` file to reflect subject matter expertise and codebase familiarity - Aim to have at least two codeowners for every repository From 90ab104d7be1b58b90b741b7066110841f7e6969 Mon Sep 17 00:00:00 2001 From: David Harris Date: Thu, 29 Feb 2024 09:15:12 -0500 Subject: [PATCH 09/16] Update links per code review This commit updates Development guide links using a reference style for gh-skeleton links in the Readme file and directly links to the skeleton list for skeletonize existing repository file. --- project_setup/README.md | 14 +++++++++----- project_setup/skeletonize-existing-repository.md | 4 +++- 2 files changed, 12 insertions(+), 6 deletions(-) diff --git a/project_setup/README.md b/project_setup/README.md index d479d32..400efa8 100644 --- a/project_setup/README.md +++ b/project_setup/README.md @@ -3,7 +3,7 @@ We recommend you follow the directions below and use a skeleton for all new repositories. -The [`gh-skeleton`](https://github.com/cisagov/gh-skeleton) GitHub CLI +The [`gh-skeleton`][gh-skeleton] GitHub CLI (`gh`) extension provides the ability to easily start new projects from the existing library of skeleton repositories. @@ -18,7 +18,7 @@ branch protection - [see our branch protection guide for details](branch-protect ## Contents ## - [Adding a skeleton configuration to an existing repository](#adding-a-skeleton-configuration-to-an-existing-repository) -- [Using the gh-skeleton `gh` extension to start a new repository](#using-the-gh-skeleton-gh-extension-to-start-a-new-repository-) +- [Using the gh-skeleton `gh` extension to start a new repository](#using-the-gh-skeleton-gh-extension-to-start-a-new-repository) - [Selecting a skeleton](#selecting-a-skeleton) - [Cloning a selected skeleton](#cloning-a-selected-skeleton) - [Create and publish the GitHub repository](#create-and-publish-the-github-repository) @@ -37,11 +37,11 @@ branch protection - [see our branch protection guide for details](branch-protect To skeletonize an existing repository, please see the guide to [skeletonize an existing repository](skeletonize-existing-repository.md). -## Using the gh-skeleton `gh` extension to start a new repository ๐Ÿ’€๐Ÿ›  ## +## Using the gh-skeleton `gh` extension to start a new repository ## We recommend that you start your project from one of the [skeleton projects](https://github.com/search?q=org%3Acisagov+topic%3Askeleton) -in this organization. The [`gh-skeleton`](https://github.com/cisagov/gh-skeleton) +in this organization. The [`gh-skeleton`][gh-skeleton] `gh` extension provides the ability to easily start new projects from the existing library of skeleton repositories. @@ -85,13 +85,15 @@ skeleton-aws-lambda ### Cloning a selected skeleton ### -Next, use the [`gh-skeleton`](https://github.com/cisagov/gh-skeleton) +Next, use the [`gh-skeleton`][gh-skeleton] `gh` extension to clone, rename, and prepare the contents of your new repository for publication. The tool will print out each command it is issuing and its result. ```console $ gh skeleton clone [options] +# Expected output: +# Cloning into 'new-repo-name' ``` For example, to create a project based on `skeleton-ansible-role` named @@ -323,3 +325,5 @@ ssm-param rm /demo/dh4096.pem /demo/private.pem /demo/public.pem 2019-08-27 16:48:02,417 INFO Deleting parameter '/demo/public.pem' in region 'us-west-1' 2019-08-27 16:48:02,795 INFO Deleting parameter '/demo/public.pem' in region 'us-west-2' ``` + +[gh-skeleton]: https://github.com/cisagov/gh-skeleton diff --git a/project_setup/skeletonize-existing-repository.md b/project_setup/skeletonize-existing-repository.md index 94a738f..10882bf 100644 --- a/project_setup/skeletonize-existing-repository.md +++ b/project_setup/skeletonize-existing-repository.md @@ -35,7 +35,7 @@ prevent merging destructive upstream changes First, decide which of the available skeletons best fits your existing non-skeletonized repository. To see a list of available skeletons, use the `gh skeleton list` command or see -the [list of skeletons](skeleton-list.md). +the [list of skeletons][skeleton-list.md]. As an example, we'll be using [`skeleton-python-library`](https://github.com/cisagov/skeleton-python-library) in this document. @@ -158,3 +158,5 @@ accumulated a number of commits on your `skeletonize` branch. The next step is to [make a pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request) and have the team perform code reviews. + +[skeleton-list.md]: https://github.com/cisagov/development-guide/blob/develop/project_setup/skeleton-list.md#available-skeletons-in-cisagov From 9df575bc9ac61af493c4e3012b54c3215cc5e6f5 Mon Sep 17 00:00:00 2001 From: David Harris Date: Thu, 29 Feb 2024 10:01:28 -0500 Subject: [PATCH 10/16] Update to Readme fragment links This commit fixes some fragment links that were not working. --- project_setup/README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/project_setup/README.md b/project_setup/README.md index 400efa8..c053d55 100644 --- a/project_setup/README.md +++ b/project_setup/README.md @@ -28,9 +28,9 @@ branch protection - [see our branch protection guide for details](branch-protect - [Setting up branch protection](#setting-up-branch-protection) - [Setting up type-specific configuration settings](#setting-up-type-specific-configuration-settings) - [Setting up Coveralls for Python projects](#setting-up-coveralls-for-python-projects) - - [Ansible requirement file generation tool ๐Ÿงป๐Ÿ› ](#ansible-requirement-file-generation-tool-) - - [Terraform IAM credentials to GitHub secrets ๐Ÿ”‘โ€๐Ÿ‘‰๐Ÿคซ](#terraform-iam-credentials-to-github-secrets-) - - [Managing SSM parameters from files ๐Ÿ—‚๐Ÿ‘‰โ˜๏ธ](#managing-ssm-parameters-from-files-%EF%B8%8F) + - [Ansible requirement file generation tool](#ansible-requirement-file-generation-tool) + - [Terraform IAM credentials to GitHub secrets](#terraform-iam-credentials-to-github-secrets) + - [Managing SSM parameters from files](#managing-ssm-parameters-from-files) ## Adding a skeleton configuration to an existing repository ## @@ -229,7 +229,7 @@ page with `Python set up for Coveralls`. The code block will have an entry for 1. Add a `New repository secret` and name it `COVERALLS_REPO_TOKEN` with the value from Coveralls. -### Ansible requirement file generation tool ๐Ÿงป๐Ÿ›  ### +### Ansible requirement file generation tool ### We have a [plethora](https://www.youtube.com/watch?v=zWld721Wk-Q) of [ansible-roles in our organization](https://github.com/search?q=org%3Acisagov+topic%3Aansible-role+NOT+skeleton+archived%3Afalse). @@ -246,7 +246,7 @@ usage of the tool is: This file will now contain definitions for all the Ansible roles. Edit the file, and remove any role that will not be required for your project. -### Terraform IAM credentials to GitHub secrets ๐Ÿ”‘โ€๐Ÿ‘‰๐Ÿคซ ### +### Terraform IAM credentials to GitHub secrets ### When GitHub Actions workflows require credentials to run we provide them via [secrets](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets). @@ -278,7 +278,7 @@ terraform-to-secrets 9f4ae878de917c7cf191b9861d3c1cf9224939f7 2020-02-22 15:50:41,036 INFO Success! ``` -### Managing SSM parameters from files ๐Ÿ—‚๐Ÿ‘‰โ˜๏ธ ### +### Managing SSM parameters from files ### Use the [`ssm-param`](scripts/ssm-param) tool to copy files into [SSM parameters](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-store-about-examples.html) From 4d326de1ae5c044e83c9f6d6f7a0f34a3371d5fb Mon Sep 17 00:00:00 2001 From: David Harris Date: Thu, 29 Feb 2024 11:39:19 -0500 Subject: [PATCH 11/16] Add suggested link and grammar changes Updates to add reference links, fragment link, and text changes to skeleton list file. --- project_setup/skeleton-list.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/project_setup/skeleton-list.md b/project_setup/skeleton-list.md index a87265b..5ba9c2a 100644 --- a/project_setup/skeleton-list.md +++ b/project_setup/skeleton-list.md @@ -4,24 +4,26 @@ We maintain a number of [`cisagov` skeleton projects](https://github.com/search? to make starting new repositories quicker and to simplify maintaining configurations and dependencies across the organization. -The [`gh-skeleton`](https://github.com/cisagov/gh-skeleton) is +The [`gh-skeleton`][gh-skeleton] project is a GitHub CLI (`gh`) extension that provides the ability to easily start new projects -from existing library of skeleton repositories. +from an existing library of skeleton repositories. - To skeletonize an existing repository, please see the guide to [skeletonize an existing repository](skeletonize-existing-repository.md). - To skeletonize a new repository, please see the guide to -[start a new repository from a skeleton](README.md). +[start a new repository from a skeleton](README.md#using-the-gh-skeleton-gh-extension-to-start-a-new-repository). ## List available skeletons with the command-line tool ## -After you've installed the [`gh` CLI](https://github.com/cli/cli) followed +After you've installed the [`gh` CLI][gh CLI] followed by the [`gh-skeleton`](https://github.com/cisagov/gh-skeleton) extension, the tool will be available to you via the command line. To see a list of available skeletons, use the following command: -```bash -gh skeleton list +```console +$ gh skeleton list +# Expected output: +# Listing of available skeleton repositories ``` ## Available skeletons in cisagov ## @@ -54,3 +56,6 @@ A skeleton project for quickly getting a new cisagov Python AWS Lambda started. Note: If you discover a new flavor of skeleton that doesn't yet exist, use `skeleton-generic` to create it, or add an issue to this repository to get assistance. + +[gh-skeleton]: https://github.com/cisagov/gh-skeleton +[gh CLI]: https://github.com/cli/cli From 1abec204597e317d05f7e7388185c80bdae0cb1c Mon Sep 17 00:00:00 2001 From: David Harris Date: Thu, 29 Feb 2024 11:53:36 -0500 Subject: [PATCH 12/16] Add text change to ReadMe command promt dollar sign text change --- project_setup/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/project_setup/README.md b/project_setup/README.md index c053d55..a3eab77 100644 --- a/project_setup/README.md +++ b/project_setup/README.md @@ -100,7 +100,9 @@ For example, to create a project based on `skeleton-ansible-role` named `ansible-role-quantum-rng` in your local `~/projects` directory: ```console -gh skeleton clone --change-dir ~/projects skeleton-ansible-role ansible-role-quantum-rng +$ gh skeleton clone --change-dir ~/projects skeleton-ansible-role ansible-role-quantum-rng +# Expected output: +# Cloning into 'repo-name' ``` This command results in: From 27e8e85290e368308c37774a9e614b88a77aa51e Mon Sep 17 00:00:00 2001 From: David Harris Date: Thu, 29 Feb 2024 12:53:26 -0500 Subject: [PATCH 13/16] Add reference link to skeleton list file Adding reference link to maintain consistency of link references globally for gh-skeleton extension tool. --- project_setup/skeleton-list.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/project_setup/skeleton-list.md b/project_setup/skeleton-list.md index 5ba9c2a..80f98b4 100644 --- a/project_setup/skeleton-list.md +++ b/project_setup/skeleton-list.md @@ -16,7 +16,7 @@ from an existing library of skeleton repositories. ## List available skeletons with the command-line tool ## After you've installed the [`gh` CLI][gh CLI] followed -by the [`gh-skeleton`](https://github.com/cisagov/gh-skeleton) extension, +by the [`gh-skeleton`][gh-skeleton] extension, the tool will be available to you via the command line. To see a list of available skeletons, use the following command: From 6f8b109d6e8740e9e61e0f19a446bc17f3d01e0b Mon Sep 17 00:00:00 2001 From: David Harris Date: Mon, 4 Mar 2024 15:43:20 -0500 Subject: [PATCH 14/16] Update output for gh skeleton list command Referenced skeleton list required update. --- project_setup/README.md | 35 +++++++++++++---------------------- 1 file changed, 13 insertions(+), 22 deletions(-) diff --git a/project_setup/README.md b/project_setup/README.md index a3eab77..27786e4 100644 --- a/project_setup/README.md +++ b/project_setup/README.md @@ -54,33 +54,24 @@ for your new repository. For a list of available skeletons, see the ```console $ gh skeleton list - - Available skeletons in cisagov: -skeleton-python-library - A skeleton project for quickly getting a new cisagov Python library started. - -skeleton-docker - A skeleton project for quickly getting a new cisagov Docker container started. - -skeleton-generic - A generic skeleton project for quickly getting a new cisagov project started. - -skeleton-tf-module - A skeleton project for quickly getting a new cisagov Terraform module started. - skeleton-ansible-role - A skeleton project for quickly getting a new cisagov Ansible role started. - +A skeleton project for quickly getting a new cisagov Ansible role started. skeleton-ansible-role-with-test-user - A skeleton project for quickly getting a new cisagov Ansible role started when that role requires an AWS test user. - +A skeleton project for quickly getting a new cisagov Ansible role started when that role requires an AWS test user. +skeleton-aws-lambda-python +A skeleton project for quickly getting a new Python-based AWS Lambda project started. +skeleton-docker +A skeleton project for quickly getting a new cisagov Docker container started. +skeleton-generic +A generic skeleton project for quickly getting a new cisagov project started. skeleton-packer - A skeleton project for quickly getting a new cisagov packer project started. - -skeleton-aws-lambda - A skeleton project for quickly getting a new cisagov Python AWS Lambda started. +A skeleton project for quickly getting a new cisagov packer project started. +skeleton-python-library +A skeleton project for quickly getting a new cisagov Python library started. +skeleton-tf-module +A skeleton project for quickly getting a new cisagov Terraform module started. ``` ### Cloning a selected skeleton ### From 868a2e04a17206b0f79fe1604a61e2cff761c9ff Mon Sep 17 00:00:00 2001 From: David Harris Date: Mon, 4 Mar 2024 16:10:23 -0500 Subject: [PATCH 15/16] Update output for gh skeleton list command #2 add back whitespace to reflect what the user should expect to see in terminal output. --- project_setup/README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/project_setup/README.md b/project_setup/README.md index 27786e4..a2c2843 100644 --- a/project_setup/README.md +++ b/project_setup/README.md @@ -58,20 +58,28 @@ Available skeletons in cisagov: skeleton-ansible-role A skeleton project for quickly getting a new cisagov Ansible role started. + skeleton-ansible-role-with-test-user A skeleton project for quickly getting a new cisagov Ansible role started when that role requires an AWS test user. + skeleton-aws-lambda-python A skeleton project for quickly getting a new Python-based AWS Lambda project started. + skeleton-docker A skeleton project for quickly getting a new cisagov Docker container started. + skeleton-generic A generic skeleton project for quickly getting a new cisagov project started. + skeleton-packer A skeleton project for quickly getting a new cisagov packer project started. + skeleton-python-library A skeleton project for quickly getting a new cisagov Python library started. + skeleton-tf-module A skeleton project for quickly getting a new cisagov Terraform module started. + ``` ### Cloning a selected skeleton ### From 201b4c749c32278d88de3b8e62bcb23baf114b6b Mon Sep 17 00:00:00 2001 From: David Harris Date: Mon, 4 Mar 2024 16:59:15 -0500 Subject: [PATCH 16/16] Update output for gh skeleton list command #3 Redo changes to formatting to reflect what the user should expect to see in terminal output. --- project_setup/README.md | 32 ++++++++------------------------ 1 file changed, 8 insertions(+), 24 deletions(-) diff --git a/project_setup/README.md b/project_setup/README.md index a2c2843..efa21ea 100644 --- a/project_setup/README.md +++ b/project_setup/README.md @@ -56,30 +56,14 @@ $ gh skeleton list Available skeletons in cisagov: -skeleton-ansible-role -A skeleton project for quickly getting a new cisagov Ansible role started. - -skeleton-ansible-role-with-test-user -A skeleton project for quickly getting a new cisagov Ansible role started when that role requires an AWS test user. - -skeleton-aws-lambda-python -A skeleton project for quickly getting a new Python-based AWS Lambda project started. - -skeleton-docker -A skeleton project for quickly getting a new cisagov Docker container started. - -skeleton-generic -A generic skeleton project for quickly getting a new cisagov project started. - -skeleton-packer -A skeleton project for quickly getting a new cisagov packer project started. - -skeleton-python-library -A skeleton project for quickly getting a new cisagov Python library started. - -skeleton-tf-module -A skeleton project for quickly getting a new cisagov Terraform module started. - +skeleton-ansible-role A skeleton project for quickly getting a new cisagov Ansible role started. +skeleton-ansible-role-with-test-user A skeleton project for quickly getting a new cisagov Ansible role started when that role requires an AWS test user. +skeleton-aws-lambda-python A skeleton project for quickly getting a new Python-based AWS Lambda project started. +skeleton-docker A skeleton project for quickly getting a new cisagov Docker container started. +skeleton-generic A generic skeleton project for quickly getting a new cisagov project started. +skeleton-packer A skeleton project for quickly getting a new cisagov packer project started. +skeleton-python-library A skeleton project for quickly getting a new cisagov Python library started. +skeleton-tf-module A skeleton project for quickly getting a new cisagov Terraform module started. ``` ### Cloning a selected skeleton ###