Comprehensive documentation overhaul and modernization - #133
Merged
Conversation
First stage of the modernization. The core, the Recipe format and the plugin contract are unchanged; what changes is that the framework runs on a current Ruby, installs from a current RubyGems, and says plainly which of its plugins still work. Documentation is the substance of this change. Added doc/REQUIREMENTS.md, doc/BASIC_DESIGN.md, doc/POLICY.md, doc/PLUGINS.md, doc/DEPLOYMENT.md, doc/LICENSE.md and doc/VERSIONS, and rewrote README.md. doc/PLUGINS.md specifies the Recipe format and the plugin contract, and catalogues all 44 plugins as Supported, Supported (external), Needs rework or Unsupported with the reason for each. The release history moved from doc/ChangeLog into doc/VERSIONS without changing an entry or a date; doc/README and doc/PLUGINS were removed once their content had a new home. doc/README.ja and doc/PLUGINS.ja are kept as historical Japanese documentation and marked as describing the software as it was. No document refers to another repository. Compatibility: Kernel#open no longer opens URLs on Ruby 3, so fetching now goes through URI.open; File.exists?, Sanitize.clean and the AWS SDK v1 requirement at load time are likewise addressed. Recipes are loaded with YAML.safe_load and a malformed one is refused with a message instead of a backtrace. The command line moved out of bin/automatic into Automatic::CLI, which returns an exit status and never calls exit, gaining -v/--version and fixed exit codes along the way. Packaging: the Jeweler-generated gemspec is replaced by a hand-maintained one stating required_ruby_version, licence and metadata. Gems needed by a single plugin are no longer runtime dependencies, so installing this no longer installs an AWS SDK. The gem source is HTTPS and gems.github.com is gone. Tests: RSpec 3, with a plugin spec skipped and named when its gem is absent rather than aborting the suite, and the examples that reach real hosts tagged :network and excluded by default. Two long-standing spec defects are fixed: one deleted the developer's real ~/.automatic/assets/siteinfo, and one failed at random on one shuffle in twenty-four. CI runs the suite on Ruby 3.2, 3.3 and 3.4 with no credential configured. Two behaviour changes worth noting: PublishConsole and PublishConsoleLink no longer print a stray "info" line before each item, and PublishInstapaper now verifies TLS certificates, which it previously disabled. No plugin was deleted, no dead service was stubbed to make a test pass, and the GPLv3 licence is unchanged. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012h5Tae3PL4LJDkT7tr1Jdw
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR replaces outdated documentation with a complete, modern specification suite and updates the codebase to match current practices.
Summary
Replaces fragmented, outdated documentation (doc/README, doc/PLUGINS, doc/ChangeLog) with a comprehensive four-document specification suite covering requirements, design, policies, and deployment. Updates the CLI architecture to be testable, modernizes Ruby compatibility to 3.2+, and improves code quality throughout.
Key Changes
Documentation
doc/REQUIREMENTS.md: Specifies what the system is for, what it accepts/produces, and responsibility boundariesdoc/BASIC_DESIGN.md: Explains composition, architecture, and how values flow through the pipelinedoc/POLICY.md: Establishes implementation rules, invariants, and change criteriadoc/PLUGINS.md: Complete specification of Recipe format and plugin contract with all shipped plugins catalogueddoc/DEPLOYMENT.md: Installation, setup, and operational guidancedoc/VERSIONS: Version history with breaking changes documenteddoc/LICENSE.md: Explicit GPL-3.0 licensing statementdoc/README.jaanddoc/PLUGINS.jaas historical documentsdoc/README,doc/PLUGINS, anddoc/ChangeLogCLI Architecture
lib/automatic/cli.rbwith testable interfaceCLI.run()returns exit status instead of callingexit(), enabling testing without process spawningbin/automaticto minimal entry point that delegates to CLIspec/lib/automatic/cli_spec.rbtest suiteRecipe Safety
YAML.safe_loadfor Recipe loading to prevent arbitrary class instantiationAutomatic::InvalidRecipeErrorfor malformed recipesAutomatic::Errorbase class for framework exceptionsspec/lib/automatic/recipe_safety_spec.rbtestsRuby Modernization
Kernel#openwithURI.openfor URL fetchingFile.exists?withFile.exist?.github/workflows/ci.ymlBuild & Packaging
automatic.gemspecfrom Jeweler-generated to hand-maintained formatVERSIONfile at build timeGemfileto reference dependencies from gemspecscript/buildwith documentation and integration test support.gitignoreto reflect modern bundler practicesCode Quality
Notable Implementation Details
https://claude.ai/code/session_012h5Tae3PL4LJDkT7tr1Jdw