search

zetachang / react.rb

Opal Ruby wrapper of React.js library.
http://reactrb.org/
MIT License
547 stars 35 forks source link

standardize repo, gem, and other related naming conventions #144

Open catmando opened 8 years ago

catmando commented 8 years ago

No place to stick an issue for a whole org, so am putting it here for discussion:

There is a new reactrb github org setup. https://github.com/reactrb

PROPOSAL 1:

Because some things will not allow names with a dot like "react.rb" (including github orgs) the proposal is that everything be standardized on reactrb.

Thus the twitter account will stay reactrb, the stackoverflow tag should change to reactrb, the documentation site will stay http://reactrb.org etc.

PROPOSAL 2:

For consistency the gem will be renamed to reactrb.

PROPOSAL 3:

we will deprecate react.rb and reactive-ruby starting with the 0.8 release.

Instead of deprecating reactive-ruby we could continue let reactive-ruby just be a mirror of reactrb which is the current proposal - but is it really needed?

PROPOSAL 4:

Repos inside the organization will be named things like "router", "rails-generator" and "reactive-record", but the gems may be prefixed with reactrb-, like "reactrb-router" and "reactrb-rails-generator" where this is appropriate. The alternative is to make the repos of any gems match the gem name. This is easier but adds redundancy.

PROPOSAL 5:

Use hypens never underscores (i.e. rails-generator)

awwaiid commented 8 years ago

I agree on all points!

Point of clarification -- In English/written context (presentations, titles) should the capitalization be:

fkchang commented 8 years ago

I like reactrb the organization name and most projects being reactrb-. I think even reactrb-record has a nice ring to the ear, sounds almost the same as reactive-record, though if reactive-router can be used outside of reactrb, then keeping it reactive-record makes sense.

I think for the gem, react.rb is good because it makes it clear that it's react, but w/ruby, ala react w/a ruby file extension. reactrb can be inferred, certainly, but one has to know to separate at the end of react, which probably isn't that much of an issue. I think spelling it out "react dot rb" is just a clearer thing visually and aurally.

Looking at reactjs, while main react.js project is under the facebook org, the org is named, reactjs, many projects are react-blah - which makes sense since react.js is the original react, though there is a react.NET under there - https://github.com/reactjs/React.NET which sort of shows a similar precedent. Of couse .NET has always been "dot net".

That being said, I'm can be swayed to towards reactrb the gem name, but since the original gem is named that, I also would still stick w/that.

panigrah commented 8 years ago

The dry-rb project also adopts a similar model, although they go with dry-rb. https://github.com/dry-rb

Proposal 1 - ok Proposal 2 - ok Proposal 3 - by deprecation - I am assuming you intend to support until 0.9 comes out and then drop it? would suggest that approach if okay. Proposal 4 - suggest official repos/gems always have reactrb- prefix to designate that they are part of the supported gems. gems under reactrb without the reactrb-prefix can be experimental, contributed or other. Proposal 5 - ok.

barriehadfield commented 8 years ago

I think the proposals are an excellent improvement

catmando commented 8 years ago

To answer some of the questions and clarify, and tell you where I think we are at:

1) I think we go with reactrb. Pros - simple, consistent, and better SEO. Cons doesn't look as good as react.rb. Lets do it okay?

2) @awwaiid raised a good point: To keep documentation consistent how do we case the name? Given its reactrb, then lets make the documentation standard be all lower: as "reactrb" (but if anyone has a rationale for something else, let us know)

3) To clarify what I mean't by deprecating the react-ruby and react.rb Gem names, this is what I had in mind:

If any one out there knows of a reason that we need to keep pushing versions of reactive-ruby please put them forward.

3) PROPOSAL 4 has had some good discussion: Consider 2 cases:

gem name repo name repo url + -
reactrb-router router https://github.com/reactrb/router better URL repo name doesn't match gem name
reactrb-router reactrb-router https://github.com/reactrb/reactrb-router simple redundant url
reactive-record reactive-record https://github.com/reactrb/reactive-record works well for non- standard gem names like reactive-record

Looking at this I am pretty convinced that overall leaving the reactrb- prefix off the repo name is the way to go, and makes sense.

catmando commented 8 years ago

regarding case: Okay well I guess I should say it should be capitalized like a normal noun. In otherwords: "Why are you using reactrb?" answer: "Reactrb is really great that is why I am using it."

fkchang commented 8 years ago

On the issue of prefixes and repository names, I think we should generally prefix the repo name with reactrb, i.e. https://github.com/reactrb/reactrb-router - the redundancy is only in url, in your local copy, you never see the redundancy. I might have another router repo locally, but unlikely I'll have another reactrb-router locally

catmando commented 8 years ago

okay I think we have a plan:

1) Name will change to reactrb across the board including the gem. I think we all hate to give up the nicer react.rb, but the inconsistency is going to cause confusion, and negatively effect SEO. For example if you search twitter for react.rb and reactrb you get two different sets of results.

2) The name "Reactrb" should be treated like a proper noun when used in sentences, first letter always capitalized (off line it was pointed out that it is a proper noun, so it should be capitalized contrary to what I said above.)

3) The reactrb gem will begin life as version 0.7.42. reactive-ruby will of course continue to exist as 0.7.41. Any future minor changes to 0.7 branch will be released only as the reactrb gem.

4) Version 0.7.42 will remove react.js source inclusion and specific opal version dependency. The react.js inclusion is a breaking change, but given that you are changing the gem name anyway, and including a version of react.js is an additional one line change, it seems good to do now, and get it over with. We are a way to go until the first 0.8 is available, but 0.7.41 is already 2 react.js versions behind, and 1 opal version behind, so it seems good to get this done now. The 0.7.42 code prints a self explanatory error message in the JS console if the react.js source is not found, so recovery from any problems is straight forward.

5) Repos inside the reactrb github org will be named exactly as the gem name. I.e. reactrb, reactrb-router, reactrb-rails-generator, reactive-ruby. (thanks to @fkchang for pointing out that leaving the reactrb- off the repo name would be inconvenient when cloning the repo.)

ajjahn commented 8 years ago

Per @catmando's request I'll go ahead and add my thoughts:

1) Name will change to reactrb across the board including the gem. I think we all hate to give up the nicer react.rb, but the inconsistency is going to cause confusion, and negatively effect SEO. For example if you search twitter for react.rb and reactrb you get two different sets of results.

Agreeable.

2) The name "Reactrb" should be treated like a proper noun when used in sentences, first letter always capitalized (off line it was pointed out that it is a proper noun, so it should be capitalized contrary to what I said above.)

Sounds good.

3) The reactrb gem will begin life as version 0.7.42. reactive-ruby will of course continue to exist as 0.7.41. Any future minor changes to 0.7 branch will be released only as the reactrb gem.

Smart.

4) Version 0.7.42 will remove react.js source inclusion and specific opal version dependency. The react.js inclusion is a breaking change, but given that you are changing the gem name anyway, and including a version of react.js is an additional one line change, it seems good to do now, and get it over with. We are a way to go until the first 0.8 is available, but 0.7.41 is already 2 react.js versions behind, and 1 opal version behind, so it seems good to get this done now. The 0.7.42 code prints a self explanatory error message in the JS console if the react.js source is not found, so recovery from any problems is straight forward.

I think we should try to stick to semver guidelines here. In general, when you introduce a breaking change, or a change that isn't backward compatible, the major version number should be incremented. Since this project is in major version zero phase, and perhaps isn't ready to graduate to 1.x.x, I would advocate at least bumping the minor version for this one. So remove react.js and go to version 0.8.x.

The key is to develop the features, and let the version number follow. The features that are planned for 0.8.x will just have to go into 0.9.x or 0.10.x or whatever.

5) Repos inside the reactrb github org will be named exactly as the gem name. I.e. reactrb, reactrb-router, reactrb-rails-generator, reactive-ruby. (thanks to @fkchang for pointing out that leaving the reactrb- off the repo name would be inconvenient when cloning the repo.)

Cool.

catmando commented 8 years ago

Okay so if I understand you @ajjahn, we make reactrb = 0.8.0 which = 0.7.41 + don't load JS, etc. All changes slated for 0.8 get added to 0.9... The only problem was we had other deprecations in 0.8, and were not going to remove them till 0.9... now that means those deprecations wont go away till 1.0 is that okay? I think we wanted 0.9 -> 1.0 to be just a "formality" but could be wrong...

dan-klasson commented 8 years ago

Yes to all points.

ajjahn commented 8 years ago

@catmando I wouldn't worry about attaching deprecations or other changes to a specific version number. Instead, bump the version number according to what's changed.

Also, remember the you can bump the minor and patch numbers as high as you need. So implementing a minor change on 0.9.x doesn't go to 1.0.0, it goes to 0.10.0.

catmando commented 8 years ago

of course :-) thanks!

sollycatprint commented 8 years ago

This issue was moved to reactrb/reactrb#144