incubator-jspwiki-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Glen Mazza <glen.ma...@gmail.com>
Subject Re: retiring the changelog file
Date Tue, 29 Jan 2013 02:10:40 GMT
Oh--I haven't been bumping up the org.apache.wiki.Release number because 
I was unaware that we needed to do that (Sorry, wasn't paying 
attention--I always wondered where that "2.9.1-svn-XX" value came from 
in the ChangeLog file...  :)  Now if I understand correctly, I *don't* 
need to bump up that number and update the ChangeLog file with trivial 
commits such as typos being fixed or should I be doing that for every 
commit?  I'm flexible here--I just need to know what to do.  (Once we 
Mavenize, incidentally, the manual incrementing numbering system might 
no longer be needed because somehow the Jenkins/Maven combination 
automatically generates snapshot bundles every day with something like a 
YYYYMMDDHH24MISS format appended to the name of the generated 
JARs/WARs.--I'm unsure here though.)

Earlier today I asked two of my coworkers, Dan Kulp and Olivier Lamy, 
who are each committers on approximately 10 Apache projects each 
(http://people.apache.org/committer-index.html , users dkulp and olamy), 
how many of their projects use manually updated change files -- Dan 
reported zero and Olivier just one (Apache Commons, as Siegfried noted 
earlier).  So that's why I'm unaccustomed to maintaining such a 
file--I've never needed it and have never heard of people on these 
projects complaining about the lack of such a file.  (Incidentally, if 
we want to highlight contributors without a change file, we can always 
add them manually to our web site page, like Apache Camel does here: 
http://camel.apache.org/team.html ) .

One small concern to keep in mind about manually maintaining a change 
log, is that it may give an "old fashioned" image to the project, 
because such files were much more common 10-15 years ago before we had 
modern repository systems.  To the point that sleekness, coolness and 
modernity in a code base drive adoption (and more committers :), 
maintaining a change log file might be furthering an older image harming 
that goal.  (It would be perhaps akin to a teenage rockstar offering his 
music additionally on cassette and phonograph records, or Apple selling 
its MacBook Pro laptops with a 3 1/2-inch diskette drive slot. In both 
cases, you're harming the image of sleekness/modernity that drives a 
portion of sales.)  Just food for thought!

Regards,
Glen

PS: Oh, to answer your question, sure, we can switch to an mdtext format 
as you propose; or switch our website to Commons Email style and just 
have it use the changes.xml directly (although I kind of like the softer 
format of our website compared to theirs -- especially since our website 
already looks much like JSPWiki :)


On 01/28/2013 03:00 PM, Juan Pablo Santos Rodríguez wrote:
> Hi,
>
> the ChangeLog shows the lists of "versions", being a "version" something
> similar to a (i.e.) Jenkins release (except that in Jenkins new release =
> new war), that is, a bunch of new functionality, which may comprise one or
> several commits. In the latter case, the Changelog file comes in handy.
>
> If a new functionality is added, the release number in
> org.apache.wiki.Release gets bumped and the ChangeLog file is updated with
> the appropiate info. Similarly a commit may not be itself worth a
> "version", i.e.: a commit to omit some auto-generated files. What
> constitutes a "version" and what not is left to the committer; as they're
> cheap to generate it isn't a big deal.
>
> Related to ChangeLog, and having mentioned Jenkins, I've just noticed that
> the ChangeLog file is very close to Markdown syntax, so we could use it to
> generate a $svn/site/trunk/content/jspwiki/development/changelog.mdtext
> That would make the contributors' names a lot more visible.
>
> A first step would have some kind of JUnit (or whatever), similar to
> TranslationsCheck, to generate the appropiate file. Then this change would
> also be committed and then published (this could be done automatically by a
> Jenkins post-job @ builds.a.o). Hmmm and we could also refresh the version
> displayed @ i.a.o/jspwiki, and also publish another page with the different
> translation statuses..
>
> thoughts?
>
>
> br,
> juan pablo
>
> On Mon, Jan 28, 2013 at 3:16 AM, Ichiro Furusato
> <ichiro.furusato@gmail.com>wrote:
>
>> [-1]
>>
>> I'm not a committer so I don't get a vote, but FWIW I've always preferred
>> human-managed change logs, since that means a human being is highlighting
>> the more important changes, new or changed APIs, features, etc. whereas
>> the machine-generated ones force me to slog through *all* of the changes.
>>
>> Yes, it does require some overhead but it's very helpful for co-developers.
>>
>> Ichiro
>>
>> On Sat, Jan 26, 2013 at 11:55 PM, Harry Metske <harry.metske@gmail.com>
>> wrote:
>>> -0.5
>>>
>>> I have always found this Changelog a very convenient mechanism of
>> searching
>>> for "what has changed when in what version".
>>> You have it one file, easily searchable and scrollable.
>>> The overhead is minimal, always cut/paste the Changelog update to the
>>> commit log.
>>> I agree that mentioned links provide all information (and more), but not
>> so
>>> easy to search, you always have to click a hundred times before you find
>>> what you want.
>>>
>>> kind regards,
>>> Harry
>>>
>>>
>>> On 25 January 2013 03:29, Glen Mazza <glen.mazza@gmail.com> wrote:
>>>
>>>> Hi team, we have a "ChangeLog" file in the root folder that is
>> apparently
>>>> (?) updated whenever someone makes a commit.  I don't see a need for it,
>>>> and none of the other Apache projects I'm aware of bothers with such a
>> file
>>>> -- it's annoying needing to update it and it just seems to be
>> unnecessary
>>>> overhead.  Can we get rid of it?
>>>>
>>>> So long as you make comments when you commit, here is a 100.0%
>>>> authoritative and chronological list of all commits made and what they
>>>> involve:
>>>> http://mail-archives.apache.**org/mod_mbox/incubator-**
>>>> jspwiki-commits/201301.mbox/**browser<
>> http://mail-archives.apache.org/mod_mbox/incubator-jspwiki-commits/201301.mbox/browser
>>>> And of course the SVN repository details the changes made to each
>> specific
>>>> file fully and accurately:
>>>> http://svn.apache.org/viewvc/**incubator/jspwiki/trunk/src/**
>>>> webdocs/Error.jsp?view=log<
>> http://svn.apache.org/viewvc/incubator/jspwiki/trunk/src/webdocs/Error.jsp?view=log
>>>> Finally, JIRA nicely provides us a list of commits per release:
>>>> https://issues.apache.org/**jira/browse/JSPWIKI#**
>>>>
>> selectedTab=com.atlassian.**jira.plugin.system.project%**3Achangelog-panel<
>> https://issues.apache.org/jira/browse/JSPWIKI#selectedTab=com.atlassian.jira.plugin.system.project%3Achangelog-panel
>>>> That should be good enough for us.  WDYT?
>>>>
>>>> Regards,
>>>> Glen
>>>>


Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message