> 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:[email protected]] > Sent: Tuesday, January 26, 2016 2:42 PM > To: dev <[email protected]> > 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 > <[email protected]> > 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.* > >
