Skip to content
This repository has been archived by the owner on Apr 14, 2021. It is now read-only.

Gemspec template should explain how spec.files works #6246

Closed
ragesoss opened this issue Jan 5, 2018 · 3 comments · Fixed by #6346
Closed

Gemspec template should explain how spec.files works #6246

ragesoss opened this issue Jan 5, 2018 · 3 comments · Fixed by #6346
Labels
good first issue help wanted type: documentation

Comments

@ragesoss
Copy link

ragesoss commented Jan 5, 2018

I think it would be useful if the gemspec created by bundle gem <gemname> had some comments explaining how the spec.files configuration works.

I recently created my first gem, and the default files config based on shelling out to git ls-files -z was opaque to me... until I spent quite a while trying to figure out why a new file I added to the gem wasn't being copied over when I ran rake install. (The answer was that I had not yet added the file to git... which I hadn't done because the gem wasn't working as intended... which was because I hadn't added it to git!)

Once I realized that the installed gem will include all the files in an array assigned to spec.files in the gemspec, it was relatively easy to figure out what the default git-based configuration was doing, and why it made sense as one option for defining the gem's files.

Adding some comments explaining what git ls-files -z is doing, and how spec.files works to define the actual code included in the installed gem, would probably be helpful for other newbie gem builders. It looks like this would just require adding some comments to newgem.gemspec.tt. I'd gladly draft a PR if this seems like a good idea.
@colby-swandale
Copy link
Member

We have a guide for using bundler to create a rubygem. Maybe we should print a banner with the link to the guide when you generate the gem to draw peoples attention to it.

@ragesoss
Copy link
Author

ragesoss commented Jan 9, 2018

That's a good idea, although not a good solution to the discoverability of spec.files, in my opinion.

I started from that guide and found it quite useful, but it's rather long, with lots of detailed sections that are about specific use cases and examples (like building a CLI), and the part that alludes to how git ls-files -z isn't really aimed teaching the reader about how to define the files in the gem... it's the in 'release your gem' section at the end, and seems to be more about getting your files committed and released than a necessary step to getting it working in the first place. (This makes sense; spec.files is probably not a topic that merits more detail in the guide.)

@nesaulov
Copy link
Contributor

I can help with this.

@nesaulov nesaulov mentioned this issue Mar 15, 2018
Merged
ragesoss added a commit to ragesoss/bundler that referenced this issue Mar 15, 2018
@ragesoss
Add documentation of spec.files to the new gem gemspec template
81a4d69 
Resolves rubygems#6246
@ragesoss ragesoss mentioned this issue Mar 15, 2018
Closed
bundlerbot added a commit that referenced this issue Mar 17, 2018
@bundlerbot
Auto merge of #6346 - nesaulov:explain-spec-files, r=segiddins
94d328b 
Explain spec files and output a link to bundler.io guides

Resolves #6246

### What was the end-user problem that led to this PR?

1. There is no helpful comment about `spec.files` method in a new gem's gemspec.
2. `$ bundle gem gem_name` is missing link to further reading about developing, testing and releasing the newly created gem.

### What is your fix for the problem, implemented in this PR?

1. Add a comment in the `newgem.gemspec.tt`
2. Add a message after new gem generation with link to [bundler.io guides](https://bundler.io/guides/creating_gem.html)

Example:
```bash
๛  ~/code/oss/tmp $  ../bundler/bin/bundle gem new_gem
Creating gem 'new_gem'...
      create  new_gem/Gemfile
      create  new_gem/lib/new_gem.rb
      create  new_gem/lib/new_gem/version.rb
      create  new_gem/new_gem.gemspec
      create  new_gem/Rakefile
      create  new_gem/README.md
      create  new_gem/bin/console
      create  new_gem/bin/setup
      create  new_gem/.gitignore
Initializing git repo in /Users/nesaulov/code/oss/tmp/new_gem
Gem 'new_gem' was successfully created. For detailed information on further steps please visit https://bundler.io/guides/creating_gem.html
๛  ~/code/oss/tmp $
```
colby-swandale pushed a commit that referenced this issue Apr 11, 2018
@bundlerbot @colby-swandale
Auto merge of #6346 - nesaulov:explain-spec-files, r=segiddins
deee215 
Explain spec files and output a link to bundler.io guides

Resolves #6246

1. There is no helpful comment about `spec.files` method in a new gem's gemspec.
2. `$ bundle gem gem_name` is missing link to further reading about developing, testing and releasing the newly created gem.

1. Add a comment in the `newgem.gemspec.tt`
2. Add a message after new gem generation with link to [bundler.io guides](https://bundler.io/guides/creating_gem.html)

Example:
```bash
๛  ~/code/oss/tmp $  ../bundler/bin/bundle gem new_gem
Creating gem 'new_gem'...
      create  new_gem/Gemfile
      create  new_gem/lib/new_gem.rb
      create  new_gem/lib/new_gem/version.rb
      create  new_gem/new_gem.gemspec
      create  new_gem/Rakefile
      create  new_gem/README.md
      create  new_gem/bin/console
      create  new_gem/bin/setup
      create  new_gem/.gitignore
Initializing git repo in /Users/nesaulov/code/oss/tmp/new_gem
Gem 'new_gem' was successfully created. For detailed information on further steps please visit https://bundler.io/guides/creating_gem.html
๛  ~/code/oss/tmp $
```

(cherry picked from commit 94d328b)
colby-swandale pushed a commit that referenced this issue Apr 20, 2018
@bundlerbot @colby-swandale
Auto merge of #6346 - nesaulov:explain-spec-files, r=segiddins
55dd644 
Explain spec files and output a link to bundler.io guides

Resolves #6246

1. There is no helpful comment about `spec.files` method in a new gem's gemspec.
2. `$ bundle gem gem_name` is missing link to further reading about developing, testing and releasing the newly created gem.

1. Add a comment in the `newgem.gemspec.tt`
2. Add a message after new gem generation with link to [bundler.io guides](https://bundler.io/guides/creating_gem.html)

Example:
```bash
๛  ~/code/oss/tmp $  ../bundler/bin/bundle gem new_gem
Creating gem 'new_gem'...
      create  new_gem/Gemfile
      create  new_gem/lib/new_gem.rb
      create  new_gem/lib/new_gem/version.rb
      create  new_gem/new_gem.gemspec
      create  new_gem/Rakefile
      create  new_gem/README.md
      create  new_gem/bin/console
      create  new_gem/bin/setup
      create  new_gem/.gitignore
Initializing git repo in /Users/nesaulov/code/oss/tmp/new_gem
Gem 'new_gem' was successfully created. For detailed information on further steps please visit https://bundler.io/guides/creating_gem.html
๛  ~/code/oss/tmp $
```

(cherry picked from commit 94d328b)
netbsd-srcmastr pushed a commit to NetBSD/pkgsrc that referenced this issue Sep 23, 2018
misc/ruby-bundler: update to 1.16.5
95654c1 
## 1.16.5 (2018-09-18)

Changes:

  - Add support for TruffleRuby (@eregon)

Bugfixes:

  - Avoid printing git errors when checking the version on incorrectly packaged versions of Bundler ([#6453](rubygems/bundler#6453), @greysteil)
  - Fix issue where Bundler does not check the given class when comparing equality in DepProxy (@ChrisBr)
  - Handle `RangeNotSatisfiable` error in Compact Index (@MaxLap)
  - Check for initialized `search` variable in `LazySpecification` (@voxik)
  - Fix LoadError occurring in nested bundle exec calls ([#6537](rubygems/bundler#6537), @colby-swandale)
  - Check that Bundler::Deprecate is not an autoload constant ([#6163](rubygems/bundler#6163), @eregon)
  - Prefer non-pre-release versions when performing a `bundle update --patch` ([#6684](rubygems/bundler#6684), @segiddins)

## 1.16.4 (2017-08-17)

Changes:

  - Welcome new members to the Bundler core team (@indirect)
  - Don't mutate original error trees when determining version_conflict_message (@greysteil)
  - Update vendored Molinillo to 0.6.6 (@segiddins)

Bugfixes:

  - Reword bundle update regression message to be more clear to the user when a gem's version is downgraded ([#6584](rubygems/bundler#6584), @ralphbolo)
  - Respect --conservative flag when updating a dependency group ([#6560](rubygems/bundler#6560), @greysteil)
  - Fix issue where a pre-release version was not being selected when it's specified in the Gemfile ([#6449](rubygems/bundler#6449), @akihiro17)
  - Fix issue where `Etc` was not loaded when getting the user's home dir ([#6640](rubygems/bundler#6640), @colby-swandale)
  - Use UTF-8 for reading files including Gemfile ([#6660](rubygems/bundler#6660), @eregon)
  - Remove unnecessary `while` loop in path resolver helper (@ojab)

Documentation:

  - Document that `bundle show [--paths]` sorts results by name (@kemitchell)

## 1.16.3 (2018-07-17)

Features:

  - Support URI::File of Ruby 2.6 (@hsbt)

Bugfixes:

  - Expand symlinks during setup to allow Bundler to load correctly when using symlinks in $GEM_HOME ([#6465](rubygems/bundler#6465), @ojab, @indirect)
  - Dont let Bundler create temporary folders for gem installs which are owned by root ([#6258](rubygems/bundler#6258), @colby-swandale)
  - Don't fallback to using temporary directories when needed directories already exist ([#6546](rubygems/bundler#6546), @brodock)
  - Use SharedHelpers.filesystem_access when reading a Gemfile so friendly error messages can be given to the user ([#6541](rubygems/bundler#6541), @segiddins)
  - Check if source responds to `#remotes` before printing gem install error message ([#6211](rubygems/bundler#6211), @colby-swandale)
  - Handle Errno::ENOTSUP in the Bundler Process Lock to prevent exceptions when using NFS mounts ([#6566](rubygems/bundler#6566), @colby-swandale)
  - Respect encodings when reading gemspecs ([#6598](rubygems/bundler#6598), @deivid-rodriguez)

Documentation:

  - Fix links between manual pages (@BanzaiMan)
  - Add warning to Gemfile documentation for the use of the `source` option when declaring gems ([#6280](rubygems/bundler#6280), @forestgagnon)

## 1.16.2 (2018-04-20)

Changes:

  - Include the gem's source in the gem install error message when available (@papanikge)
  - Remove unnecessary executable bit from gem template (@voxik)
  - Dont add the timestamp comment with gems added to the Gemfile via `bundle add` ([#6193](rubygems/bundler#6193), @cpgo)
  - Improve yanked gem error message (@alyssais)
  - Use `Bundler.rubygems.inflate` instead of the Gem::Util method directly (@segiddins)
  - Remove unused instance variable (@segiddins)

Bugfixes:

  - Only trap INT signal and have Ruby's signal default handler be invoked (@shayonj)
  - Fix warning about the use of `__FILE__` in RubyGems integration testing (@MSP-Greg)
  - Skip the outdated bundler check when MD5 is not available ([#6032](rubygems/bundler#6032), @segiddins)
  - Fallback to the original error if the friendly message raises (@segiddins)
  - Rename Bundler.frozen? to avoid Object method conflict ([#6252](rubygems/bundler#6252), @segiddins)
  - Ensure the bindir exists before installing gems (@segiddins)
  - Handle gzip corruption errors in the compact index client ([#6261](rubygems/bundler#6261), @colby-swandale)
  - Check if the current directory is writeable when writing files in `bundle gem` ([#6219](rubygems/bundler#6219), @nilsding)
  - Fix hang when gemspec has incompatible encoding (@deivid-rodriguez)
  - Gracefully handle when the lockfile is missing spec entries for the current platform ([#6079](rubygems/bundler#6079), @segiddins)
  - Use Gem::Util.inflate instead of Gem.inflate (@hsbt)
  - Update binstub generator to use new ERB.new arity in Ruby 2.6 (@koic)
  - Fix `source_location` call in rubygems integration (@MSP-Greg)
  - Use `filesystem_access` when copying files in Compact Index Updater ([#6289](rubygems/bundler#6289), @segiddins)
  - Fail gracefully when resetting git gems to the given revision fails ([#6324](rubygems/bundler#6324), @segiddins)
  - Handle exceptions that do not have a backtrace ([#6342](rubygems/bundler#6342), @nesaulov)
  - Check if stderr was closed before writing to it (@shime)
  - Handle updating a specific gem for a non-local platform ([#6350](rubygems/bundler#6350), @greysteil)
  - Bump the `bundle_binstub` check-length to 300 characters (@tduffield)
  - Fix specifying alterntive Lockfile with `bundle lock` when default gemfile is present  ([#6460](rubygems/bundler#6460), @agrim123)
  - Allow installing dependencies when the path is set to `.`  ([#6475](rubygems/bundler#6475), @segiddins)
  - Support Bundler installing on a readonly filesystem without a home directory ([#6461](rubygems/bundler#6461), @grosser)
  - Filter git uri credentials in source description (@segiddins)

Documentation:

  - Correct typos in `bundle binstubs` man page (@erikj, @samueloph)
  - Update links in `bundle gem` command documentation to use https (@KrauseFx)
  - Fix broken links between bundler man pages (@segiddins)
  - Add man page for the `bundle doctor` command ([#6243](rubygems/bundler#6243), @nholden)
  - Document `# frozen_string_literal` in `bundle init` Gemfile (@315tky)
  - Explain the gemspec files attribute in `bundle gem` template and print a link to bundler.io guides when running `bundle gem` ([#6246](rubygems/bundler#6246), @nesaulov)
  - Small copy tweaks & removed redundant phrasing in the bundler man page (@rubymorillo)
  - Improve the documentation of the settings load order in Bundler (@rubymorillo)
  - Added license info to main README (@rubymorillo)
  - Document parameters and return value of Injector#inject (@tobias-grasse)
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
good first issue help wanted type: documentation
Projects
None yet
Milestone
No milestone
3 participants
@ragesoss @colby-swandale @nesaulov