A feedback/confusion

[Radek Holy]

----- Original Message -----
> From: "Tomas Radej" <tradej at redhat.com>
> To: "General DevAssistant discussion" <devassistant at lists.fedoraproject.org>
> Cc: rholy at redhat.com
> Sent: Tuesday, May 12, 2015 6:01:53 PM
> Subject: Re: A feedback/confusion
> 
> Hi, Radek. Sorry for the time it took me to write this mail.
> 
> On 06/05/15 17:08, Radek Holy wrote:
>  > Hi, I'm slowly working on a DAP for DevAssistant. I was asked to
>  > provide some feedback. Let me share some of my initial thoughts with
>  > you.
> 
> Thanks for the feedback!
> 
>  > For me, the structure of DA's commands is really confusing. E.g. I
>  > wanted to fork and clone a GitHub project. I found out that there is
>  > a Github DAP.  Let's use it. "da modify github --help", "da modify
>  > github create --help".  Hm, no, this is not for me. OK, there is a
>  > Git DAP. No, it provides no "command". OK, let's look at all the
>  > DA's commands, maybe I'll find what I'm looking for. "da help".
>  > Well, I want to create a new project/fork and also I want to modify
>  > an existing project (it's a fork). "da create --help". What about
>  > "da create python --help". Hm, probably not. "da modify --help". Hm,
>  > nothing for me. What's remaining? "da prepare --help". But it's not
>  > going to be an upstream project! I just want to create a pull
>  > request. Anyway, "da prepare custom --help". BINGO!
> 
> I see there's a problem with documenting use cases. While the 'prep
> custom' assistant is mentioned on the front page of the documentation,
> it is lost among other use cases. You being unable to find it is a clear
> indication that it needs a highlight of some sort, or maybe renaming. I
> don't think merging it with the github DAP makes sense because `prep
> custom` can be used for non-GitHub projects as well.
> 
> I'll see what can be done about this assistant's discoverability.
> 
>  > Now, thinking about my DAP... It's going to test a pull request. As
>  > part of the tests I want to build its RPM using tito. Maybe I should
>  > extend the tito DAP and use it in my DAP. OK but what's the benefit
> 
> I am not quite sure what you mean by "extending tito DAP". The tito DAP,
> as it stands now, only contains a snippet with a run section that runs
> `tito init` and outputs info logs (more about that below).

I meant extending its functionality -- adding some commands.

>  > of duplicating the tito's CLI in order to be able to call "da modify
>  > tito build --test --rpm" if I can do the same with just "tito build
>  > --test --rpm". Let's don't do that. Now, should I create a flexible
>  > common DAP for testing any project with the ability to define in a
>  > project's .devassistant file how the given project should be tested?
>  > But looking at the current DAPs it seems that I should rather create
>  > a project specific DAP even at the risk that there are multiple
>  > projects that are tested the same way.
> 
> If you take a look at the tito snippet (the snippets/tito.yaml file
> either in ~/.devassistant, or /usr/share/devassistant), it says that
> tito itself should be invoked from the command line. You see,
> DevAssistant is not supposed to be a total wrapper over everything you
> work with. Running a command like that is so trivial that having an
> assistant just for invoking tito doesn't make much sense.
> 
> If you had a more complicated use case for testing, (e. g. compiling the
> software, creating an RPM from the compiled source, uploading the SRPM
> to Koji for building...) it would make sense to have an assistant for
> that. In that case, I believe a general assistant for RPM-based projects
> would be a good solution. I am working on a proposal for general
> assistants, it should land on this mailing list any day now.
> 
>  > But maybe I'm just lazy to think and it's clear to others.
> 
> DevAssistant as a concept (not entirely orchestration, not entirely
> shell scripting) is quite new, so I'm afraid there will always be some
> confusion. I'll make sure this happens as little as possible.
> 
> If you have more feedback about what seems counter-intuitive to you,
> please elaborate. Thanks.
> 
> Cheers, Tomas Radej


Hm, today it seems clear to me and it seems that I was really just lazy to think...

Maybe the first confusion comes from the User Documentation where the first thing which I learn is how to install DAPs. Since I found a GitHub DAP, I thought that it's what I need and ignored everything what I had learned about the DAP roles.

The second confusion was that I was so focused on creating a *GitHub fork* instead of focusing on the goal that I want to contribute to an existing project. After changing my mind, "da prepare" makes sense.


I have two concrete ideas:

* What about adding a concrete development workflow example into the User Documentation? I mean, showing step-by-step how one starts an example project, uploads it on GitHub and someone else clones it and makes a patch.
* What about reorganizing DAPI (and maybe even "da pkg") so that users first have to choose the "role" they are interested in (create/tweak/prepare/task) and only then they will see the DAPs that provides some assistant or extends some assistants that have the given role? Plus maybe a possibility to filter these using the "tags".


BTW, what still confuses me are the names of the "roles".
* "create" = "create a new project"
* "tweak" = supposedly "tweak an existing project" but it seems to me that "docker", "eclipse", "github" and "vim" rather tweak/prepare "the environment"... it depends whether one pushes the metadata of the tools (e.g. Eclipse) into the SCM repository or not... or what exactly "the project" means - everything in the repository or everything in the directory on my disk
* "prepare" = "prepare the environment"; but well, depending on the definition of "project" and "environment" it also creates or tweaks my project.

So, sometimes it refers to "the project" and sometimes to "the environment". And sometimes it seems that some assistants can have multiple roles depending on the definition of "project" and "environment". I am not sure but maybe changing the main category to just "project" and "environment" instead of "create", "tweak" etc. may be better. But still it depends on the definitions.
-- 
Radek Holý
Associate Software Engineer
Software Management Team
Red Hat Czech