[OPEN-ILS-DOCUMENTATION] Acknowledgements and Release Notes

[Kathy Lussier]

Hi all,

I've had a long-standing item on my to-do list to document the process 
of being the DIG Release Coordinator, mainly so that I can pass the role 
on to somebody else, but also so that the process is transparent to the 
rest of the community and provides opportunity for feedback. It's also 
helpful for times when the RM's take the responsibility for creating 
release notes when the DIG Release Coordinator is unavailable.

I finally started documenting the process this week, and I started a bit 
backwards by documenting how we determine whom to acknowledge in the 
release notes. I rarely get questions about the release notes 
themselves, but I have fielded several questions about who is being 
acknowledged in release notes.

The idea is to thank everyone who has played a part in the release, no 
matter how small that part may seem to the contributor, and to also 
highlight the rich and diverse community that makes an Evergreen release 
happen. I try to err on the side of inclusion in the acknowledgements if 
there is a question because  it's important we give credit to everyone 
behind the release process.

Acknowledgements were added to the release notes back in the 2.6 release 
with a contribution from Galen. I can't say how he identified 
contributors for that release, but I can say that in my early 
acknowledgements, I added the names of any author for a documentation or 
code commit that was in a particular release branch, whether it was a 
bug fix or new feature. It was fairly straightforward.

Since that time, we've added people who should be acknowledged, the most 
recent addition for the 2.11 release being people who contribute to 
translations. The method for identifying translators for a specific 
release is imperfect, but it's important that we do our best to 
acknowledge these folks since they do so much to help promote the 
international use of Evergreen.

The addition of point release notes back in the 2.8 release changed the 
way I identified contributors for a specific release. In the beginning, 
I wasn't planning to add acknowledgements for bug fixes to the point 
release notes because I knew those contributions would be acknowledged 
at the point of the major release. However, in the release notes that 
are linked on the main Downloads page, which, FWIW, look a lot different 
than the notes in the official documentation, it was confusing. The 
acknowledgements appeared to refer to all of the new features and bug 
fixes on that page, including the ones that were part of point release 
notes. However, the names were only for people who contributed to the 
major release. There was a disconnect.

As a result, my current practice is to acknowledge all bug fix 
contributions and backported documentation patches in the point release 
notes, not in the notes for a major, feature release. The major release 
acknowledgements focus on the contributors for the new features only.

I've documented the current practice for acknowledgements at 
https://wiki.evergreen-ils.org/doku.php?id=evergreen-docs:release_notes_process. 
I'm sharing this with all of you because I would like feedback from 
developers and DIG contributors on the following questions:

- Does the process for identifying who should be acknowledged for code 
and doc contributions in major release vs. point releases seem 
reasonable to people?
- Is there anyone contributing to releases that we're missing in our 
acknowledgements?
- Are there any other changes you think should be made?

If we decide to change these guidelines, I'm happy to make the necessary 
changes to the 2.11 notes.

Thanks in advance for your feedback!

Kathy


-- 
Kathy Lussier
Project Coordinator
Massachusetts Library Network Cooperative
(508) 343-0128
klussier at masslnc.org
Twitter: http://www.twitter.com/kmlussier