[forge-issues] [JBoss JIRA] (FORGE-944) Thoughts on CLI renaming on Forge 2

[Lincoln Baxter III (JIRA)]

     [ https://issues.jboss.org/browse/FORGE-944?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Lincoln Baxter III closed FORGE-944.
------------------------------------

    Resolution: Done


Closing this as done. I think we can come back to reference this if we get confused. This new strategy is working quite well. Thanks Antonio!
                
> Thoughts on CLI renaming on Forge 2
> -----------------------------------
>
>                 Key: FORGE-944
>                 URL: https://issues.jboss.org/browse/FORGE-944
>             Project: Forge
>          Issue Type: Enhancement
>          Components: Brainstorming
>    Affects Versions: 2.x Future
>            Reporter: Antonio Goncalves
>            Priority: Optional
>              Labels: cli, renaming
>             Fix For: 2.x Future
>
>
> I was talking about having CLI naming conventions on the forum and George and Lincoln suggested to add these ideas on a JIRA. So here is my humble contribution to record all the ideas about renaming commands.
> Disclaimer : I haven't used Forge for a long time, I've just started using it again, so some of the following ideas might not be accurate
> As a new comer in Forge I felt the commands were not that intuitive. I loved the following :
> {code} 
> java new-enum-type
> java new-itnerface
> java new-class
> {code}
>  
> So I was expecting to have something similar in all the other techologies, such as JPA :
> {code}
> jpa new-entity (instead of entity --named)
> jpa new-embedable
> jpa new-mapped-superclass --named Person
> jpa new-entity --named Vet --extends Person
> {code} 
> Lincoln suggested having single-level command keywords only such as :
> {code}
> jpa-new-entity (instead of entity --named)
> jpa-new-embedable
> jpa-new-mapped-superclass --named Person
> jpa-new-entity --named Vet --extends Person
> {code} 
> h3. Verbs and keywords 
> When you look at the commansd, there are several common verbs and keywords than come often : 
> {code}
> add : ejb-add-transaction-attribute
> new : beans-new-bean, faces-new-view, new-project (prefer project-new)
> list : list-web-resources, beans list-interceptors, beans list-alternatives, list-scaffold-providers
> setup : ejb setup, entity setup
> put : i18n put
> remove : i18n remove, project remove-property
> execute : execute-java
> set : maven set-groupid
> find : forge find-plugin
> install : 
> update : forge update-abort, gitignore update-repo
> run : run-url
> info : analytics info
> {code}
> That brings several thoughts : 
> * {{ls}} is used as well as {{list}}, should this be homogenize (e.g. beans-ls-interceptors)
> * {{rm}} is used as well as {{remove}}, should this be homogenize (e.g. i18n-rm, project-rm-property)
> * The difference between {{execute}} and {{run}} is not clear, should this be homogenize and only use one ?
> * Also there is {{execute}} and {{exec}}, this should be homogenize (e.g. {{execute-java}} and {{exec}})
> * Confusion between {{new}} and {{add}}. You create a new class with {{java-new-class}} and shouldn't you add a field and a method to existing class ({{java-add-field}} instead of {{java-new-field}})
> * Some confusion between {{maven}} and {{project}}
> * Is there any difference between {{set}} and {{update}} ? {{maven set-artifactid}} updates the already existing artifactId and {{gitignore update-repo}} updates an existing repo
> * we use {{field}} (e.g. {{java-add-field}}) and then property ({{constraint Future --onProperty date}}), it should be fiels ({{constraint Future --onField date}})
> In many commands you find a type argument such as ({{type}}, {{scaffoldType}}, {{fieldType}} :
> {code}
> scaffold setup --scaffoldType faces
> field manyToMany --named specialties --fieldType ~.model.Specialty.java
> field temporal --type DATE --named date
> {code}
> Why not having only {{type}} in all the cases : 
> {code}
> scaffold-setup --type faces
> jpa-add-field manyToMany --named specialties --type ~.model.Specialty.java
> jpa-add-field temporal --named date --type DATE 
> {code}
> h3. Grammar
> The CLI grammar could look like this : 
> {code}
> command = shell | forge command ;
> forge command = technology,-action,[-artifact] [{--argument value}] ;
> shell = cat | cd | cp | edit | find | grep | ls ...
> technology = project | scaffold | beans | constraint | java | jpa | i18n | ejb ...
> action = add | new | ls | rm | setup ...
> artifact = providers | interceptors | class | filter...
> argument = named | onField | type | extends
> {code}
> h3. Examples
> So if we take that grammar and apply single-level command keywords, we could have things like that : 
> {code}
> mkdir
> ls
> ls-commands -all
> project-new --named MyPro
> scaffold-ls-providers
> scaffold-templates --scaffoldType faces
> beans-ls-interceptors
> constraint-new-constraint --named MyConstraint
> constraint-add-constraint MyConstraint --onField MyProp
> java-new-class --named MyClass
> java-add-field 'private List<Vet> vets'
> java-add-method 'public List<Vet> getVetList() {return null;}'
> java-add-annotation --type XmlRootElement --onClass MyClass
> java-add-annotation --type XmlAttribute --onField MyProp
> jpa-new-mapped-superclass --named Person
> jpa-new-entity --named Vet --extends Person
> jpa-add-field manyToOne --named owner --type ~.model.Owner.java
> i18n-add-locale --locale PT
> ejb-new-stateless --named MyStateless
> ejb-new-singleton --named MySingleton --implements MyInterface AndAnotherInterface
> ejb-add-transaction-attribute --type NEVER
> ejb-add-transaction-attribute --type NEVER --onMethod MyNeverMethod
> faces-new-view --named MyView
> faces-set-project-stage --stage PRODUCTION
> servlet-new-filter --named MyFilter
> rest-new-endpoint --named MyEndpoint --extends MyRestExtension
> mvn-build --notest
> {code}
> Scaffolding is a bit tricky because it's extendable and you could end up with 
> {code}
> scaffold-ui-from-entity ~.model.*
> scaffold-rest-endpoint-from-entity ~.model.*
> scaffold-dao-from-entity ~.model.*
> scaffold-ejb-service-from-dao ~.dao.*
> scaffold-rest-endpoint-from-dao ~.dao.*
> {code}
> Or something like that
> {code}
> scaffold --ui --from-entity ~.model.*
> scaffold --rest-endpoint --from-entity ~.model.*
> scaffold --dao --from-entity ~.model.*
> scaffold --ejb-service --from-dao ~.dao.*
> scaffold --rest-endpoint --from-dao ~.dao.*
> {code}
> Here are my 2 cents thoughts on a topic that I'm discovering. As you all know, naming is really important and should be looked at carefully. Let's use this JIRA to exchange ideas.

--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira