trafodion-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Roberta Marton <roberta.mar...@esgyn.com>
Subject RE: New Version of Contributor Guide Uploaded
Date Tue, 26 Jan 2016 23:56:03 GMT
The document is good and easy to navigate.  It also contains all the
information needed to contribute to Trafodion.  Thanks Gunnar for spending
the time to do this.

I agree with Hans and Steve with their maintainability concerns.

Another concern I have is how our users view this information.  Let's say I
want to install and use Trafodion, but when I go to the page, I have to read
a book to just try out things.  From responses I received from the general
IPMC list when requesting a release candidate - not one person who verified
the release actually tried to build it.  They took a look at the steps and
deemed way to complicated.   We don't want to turn people away before they
even start.

    Roberta

-----Original Message-----
From: Steve Varnau [mailto:steve.varnau@esgyn.com]
Sent: Tuesday, January 26, 2016 3:06 PM
To: dev@trafodion.incubator.apache.org
Subject: RE: New Version of Contributor Guide Uploaded

> My one concern about this type of documentation is that it is
> wonderful when new, but because it is not really easy to maintain and
> update, it will get stale. A wiki is so much easier to change and may
> stay a bit fresher as a result. So, I think by publishing this
> document you have also volunteered to keep updating it until you have
> found another volunteer to take over this task.

I see Hans' point here.  Putting this info on the web site means it has to
go through code-review process, which is good, but also raises the the
effort to update it.  It is clear to me that we need product documents in
the code repository, but less clear to me that we need the contributor doc
there instead of the wiki.  Although it can also get stale on wiki, I think
it is more inviting of multiple people updating it.

--Steve


> -----Original Message-----
> From: Hans Zeller [mailto:hans.zeller@esgyn.com]
> Sent: Tuesday, January 26, 2016 2:42 PM
> To: dev <dev@trafodion.incubator.apache.org>
> Subject: Re: New Version of Contributor Guide Uploaded
>
> Hi Gunnar,
>
> Looks really nice overall! Here are a few comments:
>
>    - 4.3.3 "Create Pull Request": This shows "git pull-request" to
> create a
>    pull request. It should also mention that you can do this on the web by
>    going to https://github.com/apache/incubator-trafodion and pressing the
>    green "create pull request" button. Probably a nicer method that
> allows to
>    review the changes one more time before creating the pull request.
>    - 4.3.3 "Address Review Comments": Would be good to add a warning
> not to
>    use git commit --amend. Also, you could note that pushing the new
> commit is
>    enough, it will be added automatically to the pull request.
>    - 5.4: Should make it clear that one should do only one of 5.4.1 or
>    5.4.2, they are alternatives.
>    - 5.4.1 "Git": This duplicates some of the information in 4.3.3, should
>    it just reference it instead?
>    - 6.1.1 "Git": This again duplicates 4.3.3, I don't think people will
>    want to read it a third time. 6.4.2 duplicates 5.4.2.
>    - 6.3 second info block on page 29: I would add two suggestions:
>    Whenever a build finishes, always check the return code of make
> with this
>    command: "echo $?". The make output may show "BUILD SUCCEEDED", yet
> it may
>    have failed. If the build fails and you can't easily find the
> reason, rerun
>    the make command with the "-j 1" option, a non-parallel build will
> show the
>    error more clearly.
>    - 7.2.2, step 4: This also needs the "sqgen" step, in a new shell, and
>    then sqstart again in a new shell. sqgen is mentioned in section 8, but
>    people probably won't check there when they do this the first time.
>
> My one concern about this type of documentation is that it is
> wonderful when new, but because it is not really easy to maintain and
> update, it will get stale. A wiki is so much easier to change and may
> stay a bit fresher as a result. So, I think by publishing this
> document you have also volunteered to keep updating it until you have
> found another volunteer to take over this task.
>
> Thanks,
>
> Hans
>
> On Mon, Jan 25, 2016 at 10:46 PM, Gunnar Tapper
> <tapper.gunnar@gmail.com>
> wrote:
>
> > https://drive.google.com/open?id=0BxlwNhWxn8iTcXE1MlB6S3dyd0U
> >
> >
> > Updated with install and build testing results.
> >
> > --
> > Thanks,
> >
> > Gunnar
> > *If you think you can you can, if you think you can't you're right.*
> >

Mime
View raw message