-
Notifications
You must be signed in to change notification settings - Fork 129
how create a new shared collection repo
cenit_cmd is Command line utility gem to create new shared collections to be uses with Cenit Hub.
Cenit is an open source social platform as a service for data and business integration.
For create and push a new shared collection repo to github and rubygems you can follow the next main steps:
$ cenit collection foo
$ cd cenit-collection-foo
$ rake create repo
$ rake version:bump:patch release$ gem install cenit_cmd
$ cenit collection foo
By default its possible read the options from ~/gitconfig
Before proceeding, take a minute to setup your git environment, specifically setup your name and email for git and your username and token for GitHub:
$ git config --global user.email [email protected]
$ git config --global user.name 'John Doe'
$ git config --global github.user johndoe
$ git config --global github.token 55555555555555
If you prefer use explicit options then you can do
$ cenit collection foo [email protected] --github-username=sanchojaf
Other options are:
| Option | Descrition |
|---|---|
| --user-name=[USER_NAME] | the user's name, ie that is credited in the LICENSE |
| --user-email=[USER_EMAIL] | the user's email, ie that is credited in the Gem specification |
| --github-username=[GITHUB_USERNAME] | username in Github |
| --summary=[SUMMARY] | specify a summary (defaults 'Shared Collection cenit-collection-foo to be use in Cenit') |
| --description=[DESCRIPTION] | specify a description (defaults 'Shared Collection cenit-collection-foo to be use in Cenit') |
| --homepage=[HOMEPAGE] | the homepage for your project (defaults to the GitHub repo) |
- Creates the cenit-collection-foo directory
- Seeds it with some basic files:
- .gitignore, with the usual suspects predefined
- Rakefile, setup with tasks for cenit_cmd, test (TODO: add rdoc, and rcov)
- README, with your collection name and description
- LICENSE, MIT, with your name pre filled
- spec/spec_helper
- lib/cenit/collection/foo_gem.rb, placeholder library file
% tree
.
├── cenit-collection-foo.gemspec
├── Gemfile
├── .gitignore
├── .rspec
├── README.md
├── Rakefile
├── LICENSE
└── bin
└── console
└── setup
└── lib
└── cenit
└── collection
└── foo
└── connections
└── webhooks
└── connection_sets
└── translators
└── events
└── flows
└── libraries
└── index.json
└── build.rb
└── version.rb
└── foo.rb
└── spec
└── cenit
└── collection
└── foo_spec.rb
└── spec_helper.rb
└── support
└── samples
Move to the new collection folder.
$ cd cenit-collection-foo
Create a new git and related GitHub's repository
$ rake create_repo
The effect is this command is:
- this command Initializes a git repository
- Sets up [email protected]:username/cenit-collection-foo.git as the origin git remote
- Makes an initial commit
- Creates up a new repository on GitHub and pushes to it
If you have a collection in CenitHub you can export, that export the files with same structure that you need
% subtree
.
└── foo
└── connections
└── webhooks
└── connection_sets
└── translators
└── events
└── flows
└── libraries
└── index.json
If your shared collection has dependencies with others collection repo, you need add those in
nano lib/cenit/collection/foo.rbCommit and push until you are happy with your changes ...
Generate a version
$ rake version:writeTag and push release to git
$ rake git:releaseShared your collection in https://rubygems.org
$ rake releaseendeed do the last step you can putting it all together
# hack, hack, hack, commit, etc
$ rake version:bump:patch releaserun rake console
Configure your Cenithub Client API
config = {push_url: 'https://www.cenithub.com/api/v1/push',connection_key: 'My Conn Key',connection_token: 'My Conn Token'}OR
config = {push_url: 'https://www.cenithub.com/api/v1/push',user_key: 'My User Key',user_token: 'My User Token'}Show Hash Collection
Cenit::Collection::Foo.show_collection(config)Load Shared Collection into CenitHub
Cenit::Collection::Foo.push_collection(config)Setup Shared Collection into CenitHub
Cenit::Collection::Foo.pull_collection(config)Push sample data into Cenithub
Cenit::Collection::Foo.push_sample(config)Beyond just editing source code, you'll be interacting with your gem using rake a lot. To see all the tasks available with a brief description, you can run:
$ rake -T
You'll need a version before you can start installing your gem locally. The easiest way is with the version:write Rake task. Let's imagine you start with 0.1.0
$ rake version:write MAJOR=0 MINOR=1 PATCH=0
You can now go forth and develop, now that there's an initial version defined. Eventually, you should install and test the gem:
$ rake install
The install rake task builds the gem and gem installs it. You're all set if you're using RVM, but you may need to run it with sudo if you have a system-installed ruby:
$ sudo rake install
$ rake create_git_and_github_repo
At last, it's time to ship it! Make sure you have everything committed and pushed, then go wild:
$ rake release
This will automatically:
- Generate
hello-gem.gemspecand commit it - Use
gitto tagv0.1.0and push it - Build
hello-gem-0.1.0.gemand push it to rubygems.org
rake release accepts REMOTE(default: origin), LOCAL_BRANCH(default: master), REMOTE_BRANCH(default: master) and BRANCH(default: master)as options.
$ rake release REMOTE=upstream LOCAL_BRANCH=critical-security-fix REMOTE_BRANCH=v3
This will tag and push the commits on your local branch named critical-security-fix to branch named v3 in remote named upstream (if you have commit rights
on upstream) and release the gem.
$ rake release BRANCH=v3
If both remote and local branches are the same, use BRANCH option to simplify.
This will tag and push the commits on your local branch named v3 to branch named v3 in remote named origin (if you have commit rights
on origin) and release the gem.
It feels good to release code. Do it, do it often. But before that, bump the version. Then release it. There's a few ways to update the version:
# version:write like before
$ rake version:write MAJOR=0 MINOR=3 PATCH=0
# bump just major, ie 0.1.0 -> 1.0.0
$ rake version:bump:major
# bump just minor, ie 0.1.0 -> 0.2.0
$ rake version:bump:minor
# bump just patch, ie 0.1.0 -> 0.1.1
$ rake version:bump:patch
Then it's the same release we used before:
$ rake release
If you've been following along so far, your gem is just a blank slate. You're going to need to make it colorful and full of metadata.
You can customize your gem by updating your Rakefile. With a newly generated project, it will look something like this:
require 'jeweler'
Jeweler::Tasks.new do |gem|
# gem is a Gem::Specification... see http://guides.rubygems.org/specification-reference/ for more options
gem.name = "whatwhatwhat"
gem.summary = %Q{TODO: one-line summary of your gem}
gem.description = %Q{TODO: longer description of your gem}
gem.email = "[email protected]"
gem.homepage = "http://github.com/technicalpickles/whatwhatwhat"
gem.authors = ["Joshua Nichols"]
end
Jeweler::RubygemsDotOrgTasks.new
It's crucial to understand the gem object is just a Gem::Specification. You can read up about it at guides.rubygems.org/specification-reference. This is the most basic way of specifying a gem, Jeweler-managed or not. Jeweler just exposes this to you, in addition to providing some reasonable defaults, which we'll explore now.
gem.name = "whatwhatwhat"
Every gem has a name. Among other things, the gem name is how you are able to gem install it. Reference
gem.summary = %Q{TODO: one-line summary of your gem}
This is a one line summary of your gem. This is displayed, for example, when you use gem list --details or view it on rubygems.org.
gem.description = %Q{TODO: longer description of your gem}
Description is a longer description. Scholars ascertain that knowledge of where the description is used was lost centuries ago.
gem.email = "[email protected]"
This should be a way to get a hold of you regarding the gem.
gem.homepage = "http://github.com/technicalpickles/whatwhatwhat"
The homepage should have more information about your gem. The jeweler generator guesses this based on the assumption your code lives on GitHub, using your Git configuration to find your GitHub username. This is displayed by gem list --details and on rubygems.org.
gem.authors = ["Joshua Nichols"]
Hey, this is you, the author (or me in this case). The jeweler generator also guesses this from your Git configuration. This is displayed by gem list --details and on rubygems.org.
The quickest way to add more files is to git add them. Jeweler uses your Git repository to populate your gem's files by including added and committed and excluding .gitignored. In most cases, this is reasonable enough.
If you need to tweak the files, that's cool. Jeweler populates gem.files as a Rake::FileList. It's like a normal array, except you can include and exclude file globs:
gem.files.exclude 'tmp' # exclude temporary directory
gem.files.include 'lib/foo/bar.rb' # explicitly include lib/foo/bar.rb
If that's not enough, you can just set gem.files outright
gem.files = Dir.glob('lib/**/*.rb')
Dependencies let you define other gems that your gem needs to function. gem install your-gem will install your-gem's dependencies along with it, and when you use your-gem in an application, the dependencies will be made available. Use gem.add_dependency to register them. Reference
gem.add_dependency 'nokogiri'
This will ensure a version of nokogiri is installed, but it doesn't require anything more than that. You can provide extra args to be more specific:
gem.add_dependency 'nokogiri', '= 1.2.1' # exactly version 1.2.1
gem.add_dependency 'nokogiri', '>= 1.2.1' # greater than or equal to 1.2.1, ie, 1.2.1, 1.2.2, 1.3.0, 2.0.0, etc
gem.add_dependency 'nokogiri', '>= 1.2.1', '< 1.3.0' # greater than or equal to 1.2.1, but less than 1.3.0
gem.add_dependency 'nokogiri', '~> 1.2.1' # same thing, but more concise
When specifying which version is required, there's a bit of the condunrum. You want to allow the most versions possible, but you want to be sure they are compatible. Using >= 1.2.1 is fine most of the time, except until the point that 2.0.0 comes out and totally breaks backwards the API. That's when it's good to use ~> 1.2.1, which requires any version in the 1.2 family, starting with 1.2.1.
Executables let your gem install shell commands. Just put any executable scripts in the bin/ directory, make sure they are added using git, and Jeweler will take care of the rest.
When you need more finely grained control over it, you can set it yourself:
gem.executables = ['foo'] # note, it's the file name relative to `bin/`, not the project root
We discussed earlier how to bump the version. The rake tasks are really just convience methods for manipulating the VERSION file. It just contains a version string, like 1.2.3.
VERSION is a convention used by Jeweler, and is used to populate gem.version. You can actually set this yourself, and Jeweler won't try to override it:
gem.version = '1.2.3'
A common pattern is to have this in a version constant in your library. This is convenient, because users of the library can query the version they are using at runtime.
# in lib/foo/version.rb
class Foo
module Version
MAJOR = 1
MINOR = 2
PATCH = 3
BUILD = 'pre3'
STRING = [MAJOR, MINOR, PATCH, BUILD].compact.join('.')
end
end
# in Rakefile
require 'jeweler'
require './lib/foo/version.rb'
Jeweler::Tasks.new do |gem|
# snip
gem.version = Foo::Version::STRING
end
After checking out the repo, run bin/setup to install dependencies. Then, run bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release to create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.