-
Clone the repo:
git clone git@github.com:sferik/x-ruby.git -
Enter the repo’s directory:
cd x-ruby -
Install dependencies via Bundler:
bin/setupThe root,
x-core,x-uploads,x-streams, andx-resourceseach have their own bundle, sobundle updatein the root updates only the root bundle. To update them all:bin/update -
Run the default Rake task to ensure all tests pass:
bundle exec rakeEach of
x-core,x-uploads,x-streams, andx-resourceshas its ownGemfile,Rakefile,Steepfile, signatures, test suite, and mutation config, and can be checked on its own:cd x-core && bundle exec rakeFrom the root,
rake test,rake mutant,rake steep, andrake yardstickrun each gem's task inside that gem's directory, with that gem's bundle. Append a gem's name to run one, as inrake test:x-core,rake steep:x-resources, orrake yardstick:x.On GitHub, each gem's workflow runs only when that gem, or a gem it depends on, changes. The
xworkflow runs when the meta-gem or the code and signatures of any gem change, and the linter runs when any Ruby file changes. Every workflow runs whenVERSIONchanges as well, so the commit that prepares a release runs them all, which the workflow that pushes the gems waits for. A commit that changes none of the files a workflow watches, such as a fix to the documentation made after that commit, runs none of them, so run each on it before tagging it, withgh workflow run x-core.yml --ref main, andx-uploads.yml,x-streams.yml,x-resources.yml,x.yml, andlint.ymlthe same way. -
To release, write the new version to
VERSION, runrake update_versionsto write it into each gem'sversion.rb, record the release in each of the five changelogs,CHANGELOG.md,x-core/CHANGELOG.md,x-uploads/CHANGELOG.md,x-streams/CHANGELOG.md, andx-resources/CHANGELOG.md, with the link to its changes at the foot of each, commit onmain, and runrake release, which checks that the versions agree and that the branch ismain, builds every gem, tags the release asvand the version, and pushesmainand the tag, which starts the workflow that pushes the gems to RubyGems. Before the first release of a new gem, add a pending trusted publisher for it on rubygems.org, with the same repository, workflow, and environment as those ofx; it expires after 12 hours. -
Create a new branch for your feature or bug fix:
git checkout -b my-new-branch
Bug reports and pull requests are welcome on GitHub at https://github.com/sferik/x-ruby.
Pull requests will only be accepted if they meet all the following criteria:
-
Code must conform to Standard Ruby. This can be verified with:
bundle exec rake standard -
Code must conform to the RuboCop rules. This can be verified with:
bundle exec rake rubocop -
100% line, branch, and method coverage in each gem. This can be verified with:
bundle exec rake test -
100% mutation coverage in
x-core,x-uploads,x-streams, andx-resources. This can be verified with:bundle exec rake mutant -
RBS type signatures (in each gem's
sigdirectory). This can be verified with:bundle exec rake steep -
100% documentation coverage. This can be verified with:
bundle exec rake yardstickbundle exec rake yardbuilds the documentation of every gem together intodoc, or the directoryYARD_OUTPUT_DIRnames, as the Pages workflow publishes it. Each gem's.yardoptshides the API tagged@api private, so a module whose methods are public API of the class that includes it is tagged@api semipublic. The.yardoptsofx-resourcesalso passes--private, since those modules are private constants there, so every private constant of a public class or of such a module is tagged@api private, and a class opened as::X::Namenames its mixins in full in a@!parseblock;x-resources/test/x/resources/documentation_test.rbchecks all of it.