Difference between revisions of "Completed: Proposal sha.txt"

From Audacity Wiki
Jump to: navigation, search
m (Grammar.)
(Implementation: typo)
 
(8 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Proposal_Header| 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_Header| 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. <p>This solution is now employed by the Windows, OS X and Travis (Linux Ubuntu) alpha builds. However the Travis builds are not made available for download.</p> }}
 +
 
  
 
== Problem ==
 
== Problem ==
Line 9: Line 10:
 
== Proposed Feature ==
 
== Proposed Feature ==
  
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.
+
A script run at build time ensures a line with a 7 digit short SHA linking to the commit log is present in the build info window.
  
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 fromThey do not need to see the hash if we don't want that to show. 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.
+
We don't worry about users being put off by a 7 digit SHA, it's in the build info window after all, and the full sha is availableThe flexibility to change the string after build e.g. from RC2 to 'Actual Release' without affecting the exe is not needed.
  
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.
+
== Implementation ==
  
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.
+
The script contains the following line:
  
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.
+
  git show -s --format="wxT(\"<a href=\\\"http://github.com/audacity/audacity/commit/%H\\\">%h</a> of %cd\")" > ./src/RevisionIdent.h
  
 +
This overwrites an existing default version of the file, which says "No revision identifier was provided", with this line:
  
 +
wxT("<a href=\"http://github.com/audacity/audacity/commit/fe8d3535d8feb212f04bc3750a0aed77ea72f1c0\">fe8d353</a> of Thu Apr 9 10:59:42 2015 +0100")
 +
 +
This in turn in the HTML display becomes:
 +
 +
Commit Id:        fe8d353 of Thu Apr 9 10:59:42 2015 +0100
 +
 +
Where fe8d353 is hyperlinked to the commit. Note that we don't use the actual address https://github.com/audacity/audacity/<commit number> because the https:// link does not work in the About dialog.
  
 
== Developer Backing ==
 
== Developer Backing ==
 
* James Crook
 
* James Crook
 +
 +
[[Category:Proposals Completed or Withdrawn]]

Latest revision as of 05:17, 30 October 2016

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.

This solution is now employed by the Windows, OS X and Travis (Linux Ubuntu) alpha builds. However the Travis builds are not made available for download.

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.


Problem

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.

Proposed Feature

A script run at build time ensures a line with a 7 digit short SHA linking to the commit log is present in the build info window.

We don't worry about users being put off by a 7 digit SHA, it's in the build info window after all, and the full sha is available. The flexibility to change the string after build e.g. from RC2 to 'Actual Release' without affecting the exe is not needed.

Implementation

The script contains the following line:

git show -s --format="wxT(\"<a href=\\\"http://github.com/audacity/audacity/commit/%H\\\">%h</a> of %cd\")" > ./src/RevisionIdent.h

This overwrites an existing default version of the file, which says "No revision identifier was provided", with this line:

wxT("<a href=\"http://github.com/audacity/audacity/commit/fe8d3535d8feb212f04bc3750a0aed77ea72f1c0\">fe8d353</a> of Thu Apr 9 10:59:42 2015 +0100")

This in turn in the HTML display becomes:

Commit Id:        fe8d353 of Thu Apr 9 10:59:42 2015 +0100

Where fe8d353 is hyperlinked to the commit. Note that we don't use the actual address https://github.com/audacity/audacity/<commit number> because the https:// link does not work in the About dialog.

Developer Backing

  • James Crook