Completed: Proposal sha.txt
|Proposal pages help us get from feature requests into actual plans. This proposal page is about conditionally showing more build information for QA in the build info window. Specifically it is to show what source revision the build was made from|
Proposal pages are used on an ongoing basis by the Audacity development team and are open to edits from visitors to the wiki. They are a good way to get community feedback on a proposal.
- Note: Proposals for Google Summer of Code projects are significantly different in structure, are submitted via Google's web app and may or may not have a corresponding proposal page.
Gale has suggested that it would be really valuable to QA to have revision numbers actually in the builds and shown as part of the build info. That way even builds made on the same day from different source can be distinguished. It makes it easy to find what code from SVN was compiled to make that build, what changes are believed to be in, and what changes are not believed to be in. That is all vital information for QA.
Most end users don't care about revision number, so it could be argued that an actual release should not display the revision number. As we transition to Git, and with revision number like 26daea02e40796982c07b5b3f9f3cb752d54da69 it becomes even less likely that we might want to show that 'revision number' to most users. And there could also be extra work, if we build audacity RC2 and show say 'Audacity RC2' in the build info window, and now want to release it as an actual release, maybe we need to build again code that has been through test? Making it no longer tested? Oops.
The idea is simple. We add an optional text file 'sha.txt' that QA uses and that we may or may not ship with Audacity depending on whether we decide it is useful beyond QA. This file has SHAs from Git and descriptive strings. When we build audacity, the build script includes the SHA of the git branch audacity was built from in audacity.exe. That is not hard. (we dynamically create a #include file with the SHA in, which we throw away after compiling). When audacity displays the build info window, it checks for sha.txt and if present also shows revision descriptive text from sha.txt in the build info window, or default text if no shas.txt is present.
The descriptive text can be any text we decide on for that hash. It could also include a link to the relevant commit. The build info window is html after all. So a tester can open the build info window and see what revision of code the build is from. They do not need to see the hash if we don't want that to. Instead they could see some descriptive text and a link to the commit. If we don't want this information visible to most users, we don't ship the sha.txt file with audacity.
Now what if sha.txt is in our VCS? Does that cause a problem? No. The sha in audacity.exe is for the audacity source. It doesn't change if sha.txt is updates as sha.txt isn't used in building audacity.
This solution is only for audacity source code revision numbers. There is also a case for some kind of revision number for builds, zips and installers. That is a related problem and is best solved by using the object's checksum. Being clear that revision numbers in builds identify the source code, not the build means there isn't a circular problem. Builds made with different compiler tools, gcc, MSVC, tcc, will be different, but can have the same source revision number. By contrast a checksum uniquely identifies a build zip or installer, and has to live 'outside' it.
Audacity can determine its own checksum, and it can look that up in sha.txt. So we could add checksums into sha.txt too. There is less need for this, as we have checksum tools, so my suggestion is that we do the sha part first.
- James Crook