[forge-issues] [JBoss JIRA] (FORGE-944) Establish CLI naming guidelines for Forge 2

Establish CLI naming guidelines for 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: 3.0.0.Final 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.