From 54588c50e41928ff205c92740262b8221e003a78 Mon Sep 17 00:00:00 2001 From: Alex Evanczuk Date: Mon, 17 Apr 2023 15:12:25 -0400 Subject: [PATCH 1/8] move long descriptions from readme into CLI --- README.md | 18 ------------------ lib/use_packs/cli.rb | 25 +++++++++++++++++++++++++ 2 files changed, 25 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index e1142b0..9162d58 100644 --- a/README.md +++ b/README.md @@ -13,38 +13,20 @@ Make sure to run `bundle binstub use_packs` to generate `bin/packs` within your ### Moving files to packs `bin/packs move packs/your_pack_name_here path/to/file.rb path/to/directory` -This is used for moving files into a pack (the pack must already exist). -Note this works for moving files to packs from the monolith or from other packs - -Make sure there are no spaces between the comma-separated list of paths of directories. ### Moving a file to public API `bin/packs make_public path/to/file.rb,path/to/directory` -This moves a file or directory to public API (that is -- the `app/public` folder). - -Make sure there are no spaces between the comma-separated list of paths of directories. ### Listing top privacy violations `bin/packs list_top_privacy_violations packs/my_pack` -Want to create interfaces? Not sure how your pack's code is being used? - -You can use this command to list the top privacy violations. -If no pack name is passed in, this will list out violations across all packs. ### Listing top dependency violations `bin/packs list_top_dependency_violations packs/my_pack` -Want to see who is depending on you? Not sure how your pack's code is being used in an unstated way - -You can use this command to list the top dependency violations. - -If no pack name is passed in, this will list out violations across all packs. ### Adding a dependency `bin/packs add_dependency packs/my_pack packs/dependency_pack_name` -This can be used to quickly modify a `package.yml` file and add a dependency. It also cleans up the list of dependencies to sort the list and remove redundant entries. - ### Releasing Releases happen automatically through github actions once a version update is committed to `main`. diff --git a/lib/use_packs/cli.rb b/lib/use_packs/cli.rb index d0ac4ef..f979179 100644 --- a/lib/use_packs/cli.rb +++ b/lib/use_packs/cli.rb @@ -30,6 +30,13 @@ def add_dependency(from_pack, to_pack) end desc 'list_top_dependency_violations packs/your_pack', 'List the top dependency violations of packs/your_pack' + long_desc <<~LONG_DESC + Want to see who is depending on you? Not sure how your pack's code is being used in an unstated way + + You can use this command to list the top dependency violations. + + If no pack name is passed in, this will list out violations across all packs. + LONG_DESC option :limit, type: :numeric, default: 10, aliases: :l, banner: 'Specify the limit of constants to analyze' sig { params(pack_name: String).void } def list_top_dependency_violations(pack_name) @@ -40,6 +47,13 @@ def list_top_dependency_violations(pack_name) end desc 'list_top_privacy_violations packs/your_pack', 'List the top privacy violations of packs/your_pack' + long_desc <<~LONG_DESC + Want to create interfaces? Not sure how your pack's code is being used? + + You can use this command to list the top privacy violations. + + If no pack name is passed in, this will list out violations across all packs. + LONG_DESC option :limit, type: :numeric, default: 10, aliases: :l, banner: 'Specify the limit of constants to analyze' sig { params(pack_name: String).void } def list_top_privacy_violations(pack_name) @@ -50,6 +64,11 @@ def list_top_privacy_violations(pack_name) end desc 'make_public path/to/file.rb path/to/directory', 'Pass in a space-separated list of file or directory paths to make public' + long_desc <<~LONG_DESC + This moves a file or directory to public API (that is -- the `app/public` folder). + + Make sure there are no spaces between the comma-separated list of paths of directories. + LONG_DESC sig { params(paths: String).void } def make_public(*paths) UsePacks.make_public!( @@ -59,6 +78,12 @@ def make_public(*paths) end desc 'move packs/destination_pack path/to/file.rb path/to/directory', 'Pass in a destination pack and a space-separated list of file or directory paths to move to the destination pack' + long_desc <<~LONG_DESC + This is used for moving files into a pack (the pack must already exist). + Note this works for moving files to packs from the monolith or from other packs + + Make sure there are no spaces between the comma-separated list of paths of directories. + LONG_DESC sig { params(pack_name: String, paths: String).void } def move(pack_name, *paths) UsePacks.move_to_pack!( From cacee234c4afc80a0f83a98e62b47ccceff492d8 Mon Sep 17 00:00:00 2001 From: Alex Evanczuk Date: Mon, 17 Apr 2023 15:22:28 -0400 Subject: [PATCH 2/8] small tweaks to existing readme --- README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 9162d58..0652dde 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ UsePacks is a gem that helps in creating and maintaining packs. It exists to hel ## Usage Make sure to run `bundle binstub use_packs` to generate `bin/packs` within your application. -### General Help +## CLI Documentation `bin/packs --help` or just `bin/packs` to enter interactive mode. ### Pack Creation @@ -20,14 +20,13 @@ Make sure to run `bundle binstub use_packs` to generate `bin/packs` within your ### Listing top privacy violations `bin/packs list_top_privacy_violations packs/my_pack` - ### Listing top dependency violations `bin/packs list_top_dependency_violations packs/my_pack` ### Adding a dependency `bin/packs add_dependency packs/my_pack packs/dependency_pack_name` -### Releasing +## Releasing Releases happen automatically through github actions once a version update is committed to `main`. ## Discussions, Issues, Questions, and More From fd030be6d962e303d91ea3fc2892d24414998c00 Mon Sep 17 00:00:00 2001 From: Alex Evanczuk Date: Mon, 17 Apr 2023 15:26:54 -0400 Subject: [PATCH 3/8] improve existing CLI to all have the same tense --- lib/use_packs/cli.rb | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/lib/use_packs/cli.rb b/lib/use_packs/cli.rb index f979179..d89d8b5 100644 --- a/lib/use_packs/cli.rb +++ b/lib/use_packs/cli.rb @@ -63,7 +63,7 @@ def list_top_privacy_violations(pack_name) ) end - desc 'make_public path/to/file.rb path/to/directory', 'Pass in a space-separated list of file or directory paths to make public' + desc 'make_public path/to/file.rb path/to/directory', 'Make files or directories public API' long_desc <<~LONG_DESC This moves a file or directory to public API (that is -- the `app/public` folder). @@ -77,7 +77,7 @@ def make_public(*paths) ) end - desc 'move packs/destination_pack path/to/file.rb path/to/directory', 'Pass in a destination pack and a space-separated list of file or directory paths to move to the destination pack' + desc 'move packs/destination_pack path/to/file.rb path/to/directory', 'Move files or directories from one pack to another' long_desc <<~LONG_DESC This is used for moving files into a pack (the pack must already exist). Note this works for moving files to packs from the monolith or from other packs @@ -93,7 +93,7 @@ def move(pack_name, *paths) ) end - desc 'lint_package_todo_yml_files', 'Ensures `package_todo.yml` files are up to date' + desc 'lint_package_todo_yml_files', 'Lint `package_todo.yml` files to check for formatting issues' sig { void } def lint_package_todo_yml_files UsePacks.lint_package_todo_yml_files! @@ -147,7 +147,7 @@ def rename puts Private.rename_pack end - desc 'move_to_parent packs/child_pack packs/parent_pack ', 'Sets packs/child_pack as a child of packs/parent_pack' + desc 'move_to_parent packs/child_pack packs/parent_pack ', 'Set packs/child_pack as a child of packs/parent_pack' sig { params(child_pack_name: String, parent_pack_name: String).void } def move_to_parent(child_pack_name, parent_pack_name) UsePacks.move_to_parent!( From 4f36f05c459b3a0604682157b3e90df3511d0f71 Mon Sep 17 00:00:00 2001 From: Alex Evanczuk Date: Mon, 17 Apr 2023 15:22:17 -0400 Subject: [PATCH 4/8] add docs/verify_docs.rb to autogenerate docs --- docs/verify_docs.rb | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 docs/verify_docs.rb diff --git a/docs/verify_docs.rb b/docs/verify_docs.rb new file mode 100644 index 0000000..cd0e5b6 --- /dev/null +++ b/docs/verify_docs.rb @@ -0,0 +1,41 @@ +# typed: strict + +require 'bundler/inline' + +# Send is to ward off Sorbet which can't type this method invocation +send(:gemfile) do + send(:source, 'https://rubygems.org') + gem 'use_packs', path: '../' +end + +all_docs = [] +UsePacks::CLI.all_commands.each do |_command_name, command| + all_docs << <<~DOCUMENTATION + ## #{command.description} + `bin/packs #{command.usage}` + + DOCUMENTATION + + if command.long_description + all_docs << command.long_description + all_docs << "\n" + end +end + +new_autogenerated_content = <<~MARKDOWN + ## CLI Documentation + #{all_docs.join} + ## Releasing +MARKDOWN + +readme = Pathname.new('README.md') +new_content = readme.read.gsub(/## CLI Documentation.*?## Releasing/m, new_autogenerated_content) + +if ENV['OVERWRITE'] + readme.write(new_content) +elsif readme.read == new_content + exit 0 +else + puts 'README.md is out of date. Use OVERWRITE=1 ruby docs/verify_docs.rb' + exit 1 +end From 6e61ea42c56a5ed728c581fae30b428d4a93ec3d Mon Sep 17 00:00:00 2001 From: Alex Evanczuk Date: Mon, 17 Apr 2023 15:22:58 -0400 Subject: [PATCH 5/8] Add CI check --- .github/workflows/ci.yml | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9e15843..d974882 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -51,3 +51,15 @@ jobs: ruby-version: head - name: Run style checks run: bundle exec rubocop + documentation: + runs-on: ubuntu-latest + name: CLI Documentation + steps: + - uses: actions/checkout@8230315d06ad95c617244d2f265d237a1682d445 + - name: Set up Ruby + uses: ruby/setup-ruby@eae47962baca661befdfd24e4d6c34ade04858f7 + with: + bundler-cache: true + ruby-version: head + - name: Check autogenerated documentation + run: ruby docs/verify_docs.rb From afca4a1389109104a87ab95074cda7c75154f79d Mon Sep 17 00:00:00 2001 From: Alex Evanczuk Date: Mon, 17 Apr 2023 15:40:10 -0400 Subject: [PATCH 6/8] OVERWRITE=1 ruby docs/verify_docs.rb --- README.md | 87 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 74 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 0652dde..4706b59 100644 --- a/README.md +++ b/README.md @@ -6,27 +6,88 @@ UsePacks is a gem that helps in creating and maintaining packs. It exists to hel Make sure to run `bundle binstub use_packs` to generate `bin/packs` within your application. ## CLI Documentation -`bin/packs --help` or just `bin/packs` to enter interactive mode. +## Describe available commands or one specific command +`bin/packs help [COMMAND]` -### Pack Creation -`bin/packs create packs/your_pack_name_here` +## Create pack with name packs/your_pack +`bin/packs create packs/your_pack` -### Moving files to packs -`bin/packs move packs/your_pack_name_here path/to/file.rb path/to/directory` +## Add packs/to_pack to packs/from_pack/package.yml list of dependencies +`bin/packs add_dependency packs/from_pack packs/to_pack` -### Moving a file to public API -`bin/packs make_public path/to/file.rb,path/to/directory` +Use this to add a dependency between packs. -### Listing top privacy violations -`bin/packs list_top_privacy_violations packs/my_pack` +When you use bin/packs add_dependency packs/from_pack packs/to_pack, this command will +modify packs/from_pack/package.yml's list of dependencies and add packs/to_pack. -### Listing top dependency violations -`bin/packs list_top_dependency_violations packs/my_pack` +This command will also sort the list and make it unique. + +## List the top dependency violations of packs/your_pack +`bin/packs list_top_dependency_violations packs/your_pack` + +Want to see who is depending on you? Not sure how your pack's code is being used in an unstated way + +You can use this command to list the top dependency violations. + +If no pack name is passed in, this will list out violations across all packs. + +## List the top privacy violations of packs/your_pack +`bin/packs list_top_privacy_violations packs/your_pack` + +Want to create interfaces? Not sure how your pack's code is being used? + +You can use this command to list the top privacy violations. + +If no pack name is passed in, this will list out violations across all packs. + +## Make files or directories public API +`bin/packs make_public path/to/file.rb path/to/directory` + +This moves a file or directory to public API (that is -- the `app/public` folder). + +Make sure there are no spaces between the comma-separated list of paths of directories. + +## Move files or directories from one pack to another +`bin/packs move packs/destination_pack path/to/file.rb path/to/directory` + +This is used for moving files into a pack (the pack must already exist). +Note this works for moving files to packs from the monolith or from other packs + +Make sure there are no spaces between the comma-separated list of paths of directories. + +## Lint `package_todo.yml` files to check for formatting issues +`bin/packs lint_package_todo_yml_files` + +## Lint `package.yml` files +`bin/packs lint_package_yml_files [ packs/my_pack packs/my_other_pack ]` + +## Run bin/packwerk validate (detects cycles) +`bin/packs validate` + +## Run bin/packwerk check +`bin/packs check [ packs/my_pack ]` + +## Run bin/packwerk update-todo +`bin/packs update` + +## Regenerate packs/*/package_rubocop_todo.yml for one or more packs +`bin/packs regenerate_rubocop_todo [ packs/my_pack packs/my_other_pack ]` + +## Get info about size and violations for packs +`bin/packs get_info [ packs/my_pack packs/my_other_pack ]` + +## Visualize packs +`bin/packs visualize [ packs/my_pack packs/my_other_pack ]` + +## Rename a pack +`bin/packs rename` + +## Set packs/child_pack as a child of packs/parent_pack +`bin/packs move_to_parent packs/child_pack packs/parent_pack ` -### Adding a dependency -`bin/packs add_dependency packs/my_pack packs/dependency_pack_name` ## Releasing + Releases happen automatically through github actions once a version update is committed to `main`. ## Discussions, Issues, Questions, and More From 8a4906978b89a37c4a7216d6a86ec4638753fd3a Mon Sep 17 00:00:00 2001 From: Alex Evanczuk Date: Mon, 17 Apr 2023 15:41:19 -0400 Subject: [PATCH 7/8] bump version --- Gemfile.lock | 6 +++--- use_packs.gemspec | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Gemfile.lock b/Gemfile.lock index 8d1aa83..403fb02 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -17,7 +17,7 @@ GIT PATH remote: . specs: - use_packs (0.0.15) + use_packs (0.0.16) code_ownership colorize packs @@ -53,7 +53,7 @@ GEM smart_properties builder (3.2.4) byebug (11.1.3) - code_ownership (1.32.13) + code_ownership (1.32.15) code_teams (~> 1.0) packs sorbet-runtime @@ -230,4 +230,4 @@ DEPENDENCIES use_packs! BUNDLED WITH - 2.2.29 + 2.2.33 diff --git a/use_packs.gemspec b/use_packs.gemspec index e632ce5..79b4931 100644 --- a/use_packs.gemspec +++ b/use_packs.gemspec @@ -1,6 +1,6 @@ Gem::Specification.new do |spec| spec.name = 'use_packs' - spec.version = '0.0.15' + spec.version = '0.0.16' spec.authors = ['Gusto Engineers'] spec.email = ['dev@gusto.com'] From ecc171692433cab3fec8738021300d8b640dc2ba Mon Sep 17 00:00:00 2001 From: Alex Evanczuk Date: Mon, 17 Apr 2023 15:47:45 -0400 Subject: [PATCH 8/8] fix new line issue --- README.md | 1 - docs/verify_docs.rb | 2 +- 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index 4706b59..df467f7 100644 --- a/README.md +++ b/README.md @@ -87,7 +87,6 @@ Make sure there are no spaces between the comma-separated list of paths of direc ## Releasing - Releases happen automatically through github actions once a version update is committed to `main`. ## Discussions, Issues, Questions, and More diff --git a/docs/verify_docs.rb b/docs/verify_docs.rb index cd0e5b6..5636f58 100644 --- a/docs/verify_docs.rb +++ b/docs/verify_docs.rb @@ -22,7 +22,7 @@ end end -new_autogenerated_content = <<~MARKDOWN +new_autogenerated_content = <<~MARKDOWN.chomp ## CLI Documentation #{all_docs.join} ## Releasing