Allow logged documentation to be configurable (#23)

* move create and move to pack pack logging into configuration

* move remaining log events to user event logger

* Remove gusto specific things

* bump version

* remove temporary gusto config

* rubocop

Author: Alex Evanczuk

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    use_packwerk (0.55.0)
+    use_packwerk (0.56.0)
       code_ownership
       colorize
       package_protections
@@ -12,14 +12,14 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (7.0.3.1)
+    activesupport (7.0.4)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
       tzinfo (~> 2.0)
     ast (2.4.2)
     byebug (11.1.3)
-    code_ownership (1.28.0)
+    code_ownership (1.28.2)
       code_teams (~> 1.0)
       parse_packwerk
       sorbet-runtime
@@ -34,14 +34,14 @@ GEM
     json (2.6.2)
     method_source (1.0.0)
     minitest (5.16.3)
-    package_protections (1.4.0)
+    package_protections (2.2.1)
       activesupport
       parse_packwerk
       rubocop
       rubocop-sorbet
       sorbet-runtime
     parallel (1.22.1)
-    parse_packwerk (0.12.0)
+    parse_packwerk (0.12.1)
       sorbet-runtime
     parser (3.1.2.0)
       ast (~> 2.4.1)

lib/use_packwerk.rb

@@ -62,12 +62,7 @@ def self.move_to_pack!(
     per_file_processors: []
   )
     Logging.section('👋 Hi!') do
-      intro = <<~INTRO
-        You are moving a file to a pack, which is great. Check out #{UsePackwerk.config.documentation_link} for more info!
-
-        Please bring any questions or issues you have in your development process to #ruby-modularity or #product-infrastructure.
-        We'd be happy to try to help through pairing, accepting feedback, changing our process, changing our tools, and more.
-      INTRO
+      intro = UsePackwerk.config.user_event_logger.before_move_to_pack(pack_name)
       Logging.print_bold_green(intro)
     end
 
@@ -78,20 +73,7 @@ def self.move_to_pack!(
     )
 
     Logging.section('Next steps') do
-      next_steps = <<~NEXT_STEPS
-        Your next steps might be:
-
-        1) Run `bin/packwerk update-deprecations` to update the violations. Make sure to run `spring stop` if you've added new load paths (new top-level directories) in your pack.
-
-        2) Update TODO lists for rubocop implemented protections. See #{UsePackwerk.config.documentation_link} for more info
-
-        3) Touch base with each team who owns files involved in this move
-
-        4) Expose public API in #{pack_name}/app/public. Try `bin/use_packwerk make_public #{pack_name}/path/to/file.rb`
-
-        5) Update your readme at #{pack_name}/README.md
-      NEXT_STEPS
-
+      next_steps = UsePackwerk.config.user_event_logger.after_move_to_pack(pack_name)
       Logging.print_bold_green(next_steps)
     end
   end
@@ -107,9 +89,7 @@ def self.make_public!(
     per_file_processors: []
   )
     Logging.section('Making files public') do
-      intro = <<~INTRO
-        You are moving some files into public API. See #{UsePackwerk.config.documentation_link} for other utilities!
-      INTRO
+      intro = UsePackwerk.config.user_event_logger.before_make_public
       Logging.print_bold_green(intro)
     end
 
@@ -119,18 +99,7 @@ def self.make_public!(
     )
 
     Logging.section('Next steps') do
-      next_steps = <<~NEXT_STEPS
-        Your next steps might be:
-
-        1) Run `bin/packwerk update-deprecations` to update the violations. Make sure to run `spring stop` if you've added new load paths (new top-level directories) in your pack.
-
-        2) Update TODO lists for rubocop implemented protections. See #{UsePackwerk.config.documentation_link} for more info
-
-        3) Work to migrate clients of private API to your new public API
-
-        4) Update your README at packs/your_package_name/README.md
-      NEXT_STEPS
-
+      next_steps = UsePackwerk.config.user_event_logger.after_make_public
       Logging.print_bold_green(next_steps)
     end
   end
@@ -146,9 +115,7 @@ def self.add_dependency!(
     dependency_name:
   )
     Logging.section('Adding a dependency') do
-      intro = <<~INTRO
-        You are adding a dependency. See #{UsePackwerk.config.documentation_link} for other utilities!
-      INTRO
+      intro = UsePackwerk.config.user_event_logger.before_add_dependency(pack_name)
       Logging.print_bold_green(intro)
     end
 
@@ -158,14 +125,7 @@ def self.add_dependency!(
     )
 
     Logging.section('Next steps') do
-      next_steps = <<~NEXT_STEPS
-        Your next steps might be:
-
-        1) Run `bin/packwerk validate` to ensure you haven't introduced a cyclic dependency
-
-        2) Run `bin/packwerk update-deprecations` to update the violations.
-      NEXT_STEPS
-
+      next_steps = UsePackwerk.config.user_event_logger.after_add_dependency(pack_name)
       Logging.print_bold_green(next_steps)
     end
   end
@@ -183,12 +143,7 @@ def self.move_to_parent!(
     per_file_processors: []
   )
     Logging.section('👋 Hi!') do
-      intro = <<~INTRO
-        You are moving one pack to be a child of a different pack. Check out #{UsePackwerk.config.documentation_link} for more info!
-
-        Please bring any questions or issues you have in your development process to #ruby-modularity or #product-infrastructure.
-        We'd be happy to try to help through pairing, accepting feedback, changing our process, changing our tools, and more.
-      INTRO
+      intro = UsePackwerk.config.user_event_logger.before_move_to_parent(pack_name)
       Logging.print_bold_green(intro)
     end
 
@@ -199,13 +154,7 @@ def self.move_to_parent!(
     )
 
     Logging.section('Next steps') do
-      next_steps = <<~NEXT_STEPS
-        Your next steps might be:
-
-        1) Delete the old pack when things look good: `rm -rf #{pack_name}`
-
-        2) Run `bin/packwerk update-deprecations` to update the violations. Make sure to run `spring stop` first.
-      NEXT_STEPS
+      next_steps = UsePackwerk.config.user_event_logger.after_move_to_parent(pack_name)
 
       Logging.print_bold_green(next_steps)
     end

lib/use_packwerk/configuration.rb

@@ -1,41 +1,32 @@
 # typed: strict
 
+require 'use_packwerk/user_event_logger'
+require 'use_packwerk/default_user_event_logger'
+
 module UsePackwerk
   class Configuration
     extend T::Sig
 
     sig { params(enforce_dependencies: T::Boolean).void }
     attr_writer :enforce_dependencies
 
-    sig { params(documentation_link: String).void }
-    attr_writer :documentation_link
+    sig { returns(UserEventLogger) }
+    attr_accessor :user_event_logger
 
     sig { void }
     def initialize
       @enforce_dependencies = T.let(default_enforce_dependencies, T::Boolean)
-      @documentation_link = T.let(default_documentation_link, String)
+      @user_event_logger = T.let(DefaultUserEventLogger.new, UserEventLogger)
     end
 
     sig { returns(T::Boolean) }
     def enforce_dependencies
       @enforce_dependencies
     end
 
-    # Configure a link to show up for users who are looking for more info
-    sig { returns(String) }
-    def documentation_link
-      @documentation_link
-    end
-
     sig { void }
     def bust_cache!
       @enforce_dependencies = default_enforce_dependencies
-      @documentation_link = default_documentation_link
-    end
-
-    sig { returns(String) }
-    def default_documentation_link
-      'https://go/packwerk'
     end
 
     sig { returns(T::Boolean) }

lib/use_packwerk/default_user_event_logger.rb

@@ -0,0 +1,7 @@
+# typed: strict
+
+module UsePackwerk
+  class DefaultUserEventLogger
+    include UserEventLogger
+  end
+end

lib/use_packwerk/private.rb

@@ -49,12 +49,7 @@ def self.replace_in_file(file:, find:, replace_with:)
     end
     def self.create_pack!(pack_name:, enforce_privacy:, enforce_dependencies:)
       Logging.section('👋 Hi!') do
-        intro = <<~INTRO
-          You are creating a pack, which is great. Check out #{UsePackwerk.config.documentation_link} for more info!
-
-          Please bring any questions or issues you have in your development process to #ruby-modularity or #product-infrastructure.
-          We'd be happy to try to help through pairing, accepting feedback, changing our process, changing our tools, and more.
-        INTRO
+        intro = UsePackwerk.config.user_event_logger.before_create_pack(pack_name)
         Logging.print_bold_green(intro)
       end
 
@@ -65,19 +60,7 @@ def self.create_pack!(pack_name:, enforce_privacy:, enforce_dependencies:)
       add_readme_todo(package)
 
       Logging.section('Next steps') do
-        next_steps = <<~NEXT_STEPS
-          Your next steps might be:
-
-          1) Move files into your pack with `bin/use_packwerk move #{pack_name} path/to/file.rb`
-
-          2) Run `bin/packwerk update-deprecations` to update the violations. Make sure to run `spring stop` if you've added new load paths (new top-level directories) in your pack.
-
-          3) Update TODO lists for rubocop implemented protections. See #{UsePackwerk.config.documentation_link} for more info
-
-          4) Expose public API in #{pack_name}/app/public. Try `bin/use_packwerk make_public #{pack_name}/path/to/file.rb`
-
-          5) Update your readme at #{pack_name}/README.md
-        NEXT_STEPS
+        next_steps = UsePackwerk.config.user_event_logger.after_create_pack(pack_name)
 
         Logging.print_bold_green(next_steps)
       end
@@ -332,25 +315,7 @@ def self.add_public_directory(package)
 
       if public_directory.glob('**/**.rb').none?
         FileUtils.mkdir_p(public_directory)
-        todo_md = <<~TODO
-          This directory holds your public API!
-
-          Any classes, constants, or modules that you want other packs to use and you intend to support should go in here.
-          Anything that is considered private should go in other folders.
-
-          If another pack uses classes, constants, or modules that are not in your public folder, it will be considered a "privacy violation" by packwerk.
-          You can prevent other packs from using private API by using package_protections.
-
-          Want to find how your private API is being used today?
-          Try running: `bin/use_packwerk list_top_privacy_violations #{package.name}`
-
-          Want to move something into this folder?
-          Try running: `bin/use_packwerk make_public #{package.name}/path/to/file.rb`
-
-          One more thing -- feel free to delete this file and replace it with a README.md describing your package in the main package directory.
-
-          See #{UsePackwerk.config.documentation_link} for more info!
-        TODO
+        todo_md = UsePackwerk.config.user_event_logger.on_create_public_directory_todo(package.name)
         public_directory.join('TODO.md').write(todo_md)
       end
     end
@@ -360,23 +325,7 @@ def self.add_readme_todo(package)
       pack_directory = package.directory
 
       if !pack_directory.join('README.md').exist?
-        readme_todo_md = <<~TODO
-          Welcome to `#{package.name}`!
-
-          If you're the author, please consider replacing this file with a README.md, which may contain:
-          - What your pack is and does
-          - How you expect people to use your pack
-          - Example usage of your pack's public API (which lives in `#{package.name}/app/public`)
-          - Limitations, risks, and important considerations of usage
-          - How to get in touch with eng and other stakeholders for questions or issues pertaining to this pack (note: it is recommended to add ownership in `#{package.name}/package.yml` under the `owner` metadata key)
-          - What SLAs/SLOs (service level agreements/objectives), if any, your package provides
-          - When in doubt, keep it simple
-          - Anything else you may want to include!
-
-          README.md files are under version control and should change as your public API changes.#{' '}
-
-          See #{UsePackwerk.config.documentation_link} for more info!
-        TODO
+        readme_todo_md = UsePackwerk.config.user_event_logger.on_create_readme_todo(package.name)
         pack_directory.join('README_TODO.md').write(readme_todo_md)
       end
     end