incubator-cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Hugo Trippaers <HTrippa...@schubergphilis.com>
Subject RE: Small note on the Apache CS docs, advice on quick fixes
Date Thu, 07 Feb 2013 08:00:08 GMT


> From: Jessica Tomechak [mailto:Jessica.Tomechak@citrix.com] 
> Sent: Thursday, February 07, 2013 3:20 AM
> To: Hugo Trippaers
> Cc: Radhika Puthiyetath
> Subject: Small note on the Apache CS docs, advice on quick fixes
>
> Hi Hugo,
> I noticed a couple of doc changes you made lately and I'd like to offer some friendly
advice.
>
> As I was browsing through the git logs today, I happened to see a commit message that
made me want to click:
>
> "XML likes it when you close tags as well"
> d70327ae15ecbf92d8dd5e3ed5b1ee6fc4a8bdd9  
>
> The missing close para tag was not a simple oversight, but a clue to a larger issue.
The whole second half of the paragraph had been deleted at some point, maybe during a merge
conflict resolution. So when you see something like this, my advice is that it's worth asking
"Why" before fixing.

You are absolutely right of course, I should have investigated further. However the underlying
problem here was that a whole lot of changes were merged into the master branch on short notice.
This resulted in a number of Jenkins jobs failing and I decided to "fix" the issues and get
the builds going again as the sheer number of commits was too big to properly investigate.
If I find that I need to do the same in the future, I will raise a ticket pointing to the
commit so it can be followed up. 

>
> I also noticed you commented out a couple of bad hyperlinks <!--FIXME like this -->,
rather than fixing them. I get that this quick-and-dirty approach could be necessary right
before a > deadline. I would suggest that when you do this, it would be helpful to comment
out the entire sentence, so the docs don't end up with text like "See  ."
>
> Also it would be helpful to file a bug about the broken links, with the Component field
set to Doc, so someone else might fix it. Or maybe everyone but me is routinely grepping the
repo > for the text FIXME? I don't know. The bugbase is where I look.

Sorry about that, I'm so used to eclipse that I forget that not everybody is using it. In
my ide setup every line that contains FIXME is present in nice bright red colors at the top
of my task list, so I regularly just include a dirty fix and make a mention of it with FIXME
so I won't forget to deal with it later. Again raising a bug would have been more useful in
retrospect :-)

>
> I hope this is helpful. Cc'ing another writer for her benefit. You can feel free to fwd
to the list if you think that such specific advice would be helpful to others.
>
Certainly helpful, I think all of us need regular reminding that not everybody has the same
way of working and that we need to make sure that information is properly shared. Will CC
the list as reminders like this can't be repeat enough.

>
> Jessica T.
> CloudStack Tech Pubs



Mime
View raw message