[U-Boot] [PATCH 1/2] scripts: add a utility to fill blank fields of doc/README.scrapyard

[Simon Glass]

Hi Masahiro,

On 13 January 2015 at 11:13, Masahiro Yamada <yamada.m at jp.panasonic.com> wrote:
> We are removing bunch of non-generic boards these days.
>
> Updating doc/README.scrapyard is a really tedious task, but it can
> be automated.  I hope this tool will make our life easier.
>
> Signed-off-by: Masahiro Yamada <yamada.m at jp.panasonic.com>
> ---
>
>  scripts/fill_scrapyard.py | 168 ++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 168 insertions(+)
>  create mode 100755 scripts/fill_scrapyard.py

Reviewed-by: Simon Glass <sjg at chromium.org>

Note there is gitutils.GetTopLevel() available. I don't think you want
to use the patman libraries, but thought I would mention it.

>
> diff --git a/scripts/fill_scrapyard.py b/scripts/fill_scrapyard.py
> new file mode 100755
> index 0000000..6895c9f
> --- /dev/null
> +++ b/scripts/fill_scrapyard.py
> @@ -0,0 +1,168 @@
> +#!/usr/bin/env python2
> +#
> +# Author: Masahiro Yamada <yamada.m at jp.panasonic.com>
> +#
> +# SPDX-License-Identifier:     GPL-2.0+
> +#
> +
> +"""
> +Fill the "Commit" and "Removed" fields of doc/README.scrapyard
> +
> +The file doc/README.scrapyard is used to keep track of removed boards.
> +
> +When we remove support for boards, we are supposed to add entries to
> +doc/README.scrapyard leaving "Commit" and "Removed" fields blank.
> +
> +The "Commit" field is the commit hash in which the board was removed
> +and the "Removed" is the date at which the board was removed.  Those
> +two are known only after the board removal patch was applied, thus they
> +need to be filled in later.
> +
> +This effectively means that the person who removes another board is
> +first supposed to fill in the blank fields and then add the board that
> +is being removed, again with blank fields for the commit hash and date
> +of removal.
> +
> +That is a really tedious task that should be automated.
> +This script fills the blank fields of doc/README.scrapyard for you!
> +
> +Usage:
> +
> +The "Commit" and "Removed" fields must be "-".  The other fields should
> +have already been filled in by a former commit.
> +
> +Run
> +    scripts/fill_scrapyard.py
> +"""
> +
> +import os
> +import subprocess
> +import sys
> +import tempfile
> +
> +DOC='doc/README.scrapyard'
> +
> +def get_last_modify_commit(file, line_num):
> +    """Get the commit that last modified the given line.
> +
> +    This function runs "git blame" against the given line of the given
> +    file and returns the commit hash that last modified it.
> +
> +    Arguments:
> +      file: the file to be git-blame'd.
> +      line_num: the line number to be git-blame'd.  This line number
> +                starts from 1, not 0.
> +
> +    Returns:
> +      Commit hash that last modified the line.  The number of digits is
> +      long enough to form a unique commit.
> +    """
> +    result = subprocess.check_output(['git', 'blame', '-L',
> +                                      '%d,%d' % (line_num, line_num), file])
> +    commit = result.split()[0]
> +
> +    if commit[0] == '^':
> +        sys.exit('%s: line %d: ' % (file, line_num) +
> +                 'this line was modified before the beginning of git history')
> +
> +    if commit == '0' * len(commit):
> +        sys.exit('%s: line %d: locally modified\n' % (file, line_num) +
> +                 'Please run this tool in a clean repository.')
> +
> +    return commit
> +
> +def get_committer_date(commit):
> +    """Get the committer date of the given commit.
> +
> +    This function returns the date when the given commit was applied.
> +
> +    Arguments:
> +      commit: commit-ish object.
> +
> +    Returns:
> +      The committer date of the given commit in the form YY-MM-DD.
> +    """
> +    committer_date = subprocess.check_output(['git', 'show', '-s',
> +                                              '--format=%ci', commit])
> +    return committer_date.split()[0]
> +
> +def move_to_topdir():
> +    """Change directory to the top of the git repository.
> +
> +    Or, exit with an error message if called out of a git repository.
> +    """
> +    try:
> +        toplevel = subprocess.check_output(['git', 'rev-parse',
> +                                            '--show-toplevel'])
> +    except subprocess.CalledProcessError:
> +        sys.exit('Please run in a git repository.')
> +
> +    # strip '\n'
> +    toplevel = toplevel.rstrip()
> +
> +    # Change the current working directory to the toplevel of the respository
> +    # for our easier life.
> +    os.chdir(toplevel)
> +
> +class TmpFile:
> +
> +    """Useful class to handle a temporary file.
> +
> +    tempfile.mkstemp() is often used to create a unique temporary file,
> +    but what is inconvenient is that the caller is responsible for
> +    deleting the file when done with it.
> +
> +    Even when the caller errors out on the way, the temporary file must
> +    be deleted somehow.  The idea here is that we delete the file in
> +    the destructor of this class because the destructor is always
> +    invoked when the instance of the class is freed.
> +    """
> +
> +    def __init__(self):
> +        """Constructor - create a temporary file"""
> +        fd, self.filename = tempfile.mkstemp()
> +        self.file = os.fdopen(fd, 'w')
> +
> +    def __del__(self):
> +        """Destructor - delete the temporary file"""
> +        try:
> +            os.remove(self.filename)
> +        except:
> +            pass
> +
> +def main():
> +    move_to_topdir()
> +
> +    with open(DOC) as f:
> +        lines = f.readlines()
> +
> +    line_num = 1
> +
> +    tmpfile = TmpFile()
> +    for line in open(DOC):
> +        tmp = line.split(None, 5)
> +        modified = False
> +
> +        if len(tmp) >= 5:
> +            if tmp[3] == '-':
> +                tmp[3] = get_last_modify_commit(DOC, line_num)
> +                modified = True
> +            if tmp[4] == '-':
> +                tmp[4] = get_committer_date(tmp[3])
> +            if modified:
> +                line  = tmp[0].ljust(17)
> +                line += tmp[1].ljust(12)
> +                line += tmp[2].ljust(15)
> +                line += tmp[3].ljust(12)
> +                line += tmp[4].ljust(12)
> +                if len(tmp) >= 6:
> +                    line += tmp[5]
> +                line = line.rstrip() + '\n'
> +
> +        tmpfile.file.write(line)
> +        line_num += 1
> +
> +    os.rename(tmpfile.filename, DOC)
> +
> +if __name__ == '__main__':
> +    main()
> --
> 1.9.1
>

Regards,
Simon