Rename placeholder variables

mhucka · mhucka · commit 5ce03c7ecc22 · 2022-12-11T19:36:46.000-08:00
I confused %PROJECT_NAME% and %PROJECT_URLNAME% too many times, and
decided to stop it by naming them in a way that I hope makes it more
obvious what they are.
diff --git a/.flake8 b/.flake8
@@ -3,7 +3,7 @@
 # @brief   Project-wide Flake8 configuration
 # @created %CREATION_DATE%
 # @license Please see the file named LICENSE in the project directory
-# @website https://github.com/caltechlibrary/%PROJECT_URLNAME%
+# @website https://github.com/caltechlibrary/%REPO_NAME%
 #
 # Note: as of version 4.0, flake8 does NOT read global configuration files
 # from ~/.flake8 or ~/.config/flake8.  If you had such a config file of your
@@ -47,4 +47,4 @@ per-file-ignores =
     # keyword/parameter equals"). It would be better to disable E251 just for
     # that block in the file, BUT flake8 only recognizes per-line annotations,
     # so there's no way to tell it to ignore a rule only for a block of code.
-    %PROJECT_NAME%/__main__.py: E251
+    %MODULE_NAME%/__main__.py: E251
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -5,8 +5,6 @@ Please summarize what this pull request is about, and what it changes.
 ### Details
 
 Describe more about the changes you made:
-1. (...)
-2. (...)
 
 ### Software versions
 
diff --git a/.github/rename_project.sh b/.github/rename_project.sh
@@ -11,14 +11,13 @@
 # The original file was copied on 2021-10-14.
 # =============================================================================
 
-while getopts a:e:n:u:d: flag
-do
+while getopts a:e:n:u:d: flag; do
     case "${flag}" in
         a) author=${OPTARG};;
-        e) email=${OPTARG};;
-        n) project_name=${OPTARG};;
-        u) urlname=${OPTARG};;
         d) description=${OPTARG};;
+        e) email=${OPTARG};;
+        m) module_name=${OPTARG};;
+        r) repo_name=${OPTARG};;
     esac
 done
 
@@ -32,32 +31,34 @@ echo "Author name: $author"
 echo "Author first name: $first_name"
 echo "Author family name: $family_name"
 echo "Author email: $email"
-echo "Project name: $project_name"
-echo "Project URL name: $urlname"
+echo "Repo name: $repo_name"
+echo "Module name: $module_name"
 echo "Description: $description"
 echo "Creation date: $creation_date"
 echo "Creation year: $creation_year"
 
-echo "Renaming project ..."
+echo "Performing substitutions in files ..."
 
 for filename in $(git ls-files)
 do
     sed -i "s/%AUTHOR_NAME%/$author/g" $filename
     sed -i "s/%AUTHOR_EMAIL%/$email/g" $filename
     sed -i "s/%AUTHOR_FIRST_NAME%/$first_name/g" $filename
     sed -i "s/%AUTHOR_FAMILY_NAME%/$family_name/g" $filename
-    sed -i "s/%PROJECT_NAME%/$project_name/g" $filename
-    sed -i "s/%PROJECT_URLNAME%/$urlname/g" $filename
-    sed -i "s/%PROJECT_DESCRIPTION%/$description/g" $filename
+    sed -i "s/%REPO_NAME%/$repo_name/g" $filename
+    sed -i "s/%DESCRIPTION%/$description/g" $filename
+    sed -i "s/%MODULE_NAME%/$module_name/g" $filename
     sed -i "s/%CREATION_DATE%/$creation_date/g" $filename
     sed -i "s/%CREATION_YEAR%/$creation_year/g" $filename
-    echo "Performed substitutions in $filename"
+    echo "Finished substitutions in $filename"
 done
 
-mv project_name $project_name
+echo "Renaming files and directories ..."
+
+mv module_name $module_name
 rm -f codemeta.json
 mv codemeta-TEMPLATE.json codemeta.json
 rm -f CITATION.cff
 mv CITATION-TEMPLATE.cff CITATION.cff
 
-echo "Renaming project ... Done."
+echo "Renaming ... Done."
diff --git a/.github/workflows/rename_project.yml b/.github/workflows/rename_project.yml
@@ -31,11 +31,18 @@ jobs:
           # Token needs to be set in order to use the GitHub CLI `gh` program.
           GH_TOKEN: ${{ github.token }}
         run: |
-          echo NAME="$(gh repo view --json name -q .name | tr '[:upper:]' '[:lower:]')"     >> $GITHUB_ENV
-          echo URLNAME="$(gh repo view --json name -q .name)"                               >> $GITHUB_ENV
-          echo AUTHOR="$(gh api https://api.github.com/users/${{ github.actor }} -q .name)" >> $GITHUB_ENV
-          echo EMAIL="$(gh api https://api.github.com/users/${{ github.actor }} -q .email)" >> $GITHUB_ENV
-          echo DESCRIPTION="$(gh repo view --json description -q .description)"             >> $GITHUB_ENV
+          # The meanings of the variables:
+          #  REPO_NAME = the repository name used on GitHub at creation time
+          #  MODULE_NAME = like NAME but all lower-case
+          #  DESCRIPTION = the description given on GitHub at creation time
+          #  AUTHOR = the name of the author
+          #  EMAIL = the email address of the author
+
+          echo REPO_NAME="$(gh repo view --json name -q .name)"                                >> $GITHUB_ENV
+          echo MODULE_NAME="$(gh repo view --json name -q .name | tr '[:upper:]' '[:lower:]')" >> $GITHUB_ENV
+          echo DESCRIPTION="$(gh repo view --json description -q .description)"                >> $GITHUB_ENV
+          echo AUTHOR="$(gh api https://api.github.com/users/${{ github.actor }} -q .name)"    >> $GITHUB_ENV
+          echo EMAIL="$(gh api https://api.github.com/users/${{ github.actor }} -q .email)"    >> $GITHUB_ENV
 
       - name: Test that this is a repo based on our template.
         id: check_template
@@ -48,7 +55,7 @@ jobs:
         shell: bash
         run: |
           echo "Performing substitutions."
-          .github/rename_project.sh -a "${{ env.AUTHOR }}" -e "${{ env.EMAIL }}" -n "${{ env.NAME }}" -u "${{ env.URLNAME }}" -d "${{ env.DESCRIPTION }}"
+          .github/rename_project.sh -a "${{ env.AUTHOR }}" -e "${{ env.EMAIL }}" -r "${{ env.REPO_NAME }}" -m "${{ env.MODULE_NAME }}" -d "${{ env.DESCRIPTION }}"
 
       - name: Clean up.
         shell: bash
diff --git a/.gitignore b/.gitignore
@@ -3,7 +3,7 @@
 # @brief   Files and patterns for files and subdirs that git should ignore
 # @date    %CREATION_DATE%
 # @license Please see the file named LICENSE in the project directory
-# @website https://github.com/caltechlibrary/%PROJECT_URLNAME%
+# @website https://github.com/caltechlibrary/%REPO_NAME%
 #
 # The approach we suggest is to add ONLY project-specific rules here. Put
 # rules that apply to your way of doing things (and the particular tools you
diff --git a/CHANGES.md b/CHANGES.md
@@ -1,6 +1,6 @@
-# Change log for %PROJECT_NAME%
+# Change log for %REPO_NAME%
 
 ## Version 0.0.0 (%CREATION_DATE%)
 
-Project repository created at https://github.com/caltechlibrary/%PROJECT_URLNAME%
+Project repository created at https://github.com/caltechlibrary/%REPO_NAME%
 by %AUTHOR_NAME%.
diff --git a/CITATION-TEMPLATE.cff b/CITATION-TEMPLATE.cff
@@ -1,16 +1,16 @@
 cff-version: 1.2
 message: "If you use this software, please cite it using these metadata."
-title: "%PROJECT_NAME%"
+title: "%REPO_NAME%"
 authors: 
   - family-names: %AUTHOR_FAMILY_NAME%
     given-names: %AUTHOR_FIRST_NAME%
     affiliation: "Caltech Library"
     orcid: "https://orid.org/YOUR-ORCID-NUMBER"
 version: "0.0.0"
-abstract: "%PROJECT_DESCRIPTION%"
-repository-code: "https://github.com/caltechlibrary/%PROJECT_URLNAME%"
+abstract: "%DESCRIPTION%"
+repository-code: "https://github.com/caltechlibrary/%REPO_NAME%"
 type: software
-license-url: "https://github.com/caltechlibrary/%PROJECT_URLNAME%/blob/main/LICENSE"
+license-url: "https://github.com/caltechlibrary/%REPO_NAME%/blob/main/LICENSE"
 keywords: 
   - "KEYWORDS"
 date-released: "RELEASE-DATE"
diff --git a/CITATION.cff b/CITATION.cff
@@ -23,7 +23,7 @@ authors:
     family-names: Keswick
     orcid: "https://orcid.org/0000-0001-5644-440X"
 version: "1.9.0"
-abstract: "GitHub template project for non-web Python application projects"
+abstract: "GitHub repository template for non-web Python programs"
 repository-code: "https://github.com/caltechlibrary/py-cli-template"
 type: software
 license-url: "https://github.com/caltechlibrary/py-cli-template/blob/main/LICENSE"
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,4 +1,4 @@
-# Guidelines for contributing to this project
+# Guidelines for contributing to this project repository
 
 Any constructive contributions &ndash; bug reports, pull requests (code or documentation), suggestions for improvements, and more &ndash; are welcome.
 
@@ -8,7 +8,7 @@ Everyone is asked to read and respect the [code of conduct](CODE_OF_CONDUCT.md)
 
 ## Coordinating work
 
-A quick way to find out what is currently in the near-term plans for this project is to look at the [GitHub issue tracker](https://github.com/caltechlibrary/%PROJECT_URLNAME%/issues), but the possibilities are not limited to what you see there &ndash; if you have ideas for new features and enhancements, please feel free to write them up as a new issue or contact the developers directly!
+A quick way to find out what is currently in the near-term plans for this project is to look at the [GitHub issue tracker](https://github.com/caltechlibrary/%REPO_NAME%/issues), but the possibilities are not limited to what you see there &ndash; if you have ideas for new features and enhancements, please feel free to write them up as a new issue or contact the developers directly!
 
 ## Submitting contributions
 
diff --git a/Makefile b/Makefile
@@ -3,7 +3,7 @@
 # @brief   Makefile for some steps in creating new releases on GitHub
 # @date    %CREATION_DATE%
 # @license Please see the file named LICENSE in the project directory
-# @website https://github.com/caltechlibrary/%PROJECT_URLNAME%
+# @website https://github.com/caltechlibrary/%REPO_NAME%
 # =============================================================================
 
 .ONESHELL:                              # Run all commands in the same shell.
@@ -146,10 +146,10 @@ report: vars
 # make lint & make test ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 lint:
-	flake8 %PROJECT_URLNAME%
+	flake8 %MODULE_NAME%
 
 test tests:;
-	pytest -v --cov=%PROJECT_URLNAME% -l tests/
+	pytest -v --cov=%MODULE_NAME% -l tests/
 
 
 # make install ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/README.md b/README.md
@@ -1,9 +1,9 @@
-# %PROJECT_NAME%
+# %REPO_NAME%
 
-%PROJECT_DESCRIPTION%
+%DESCRIPTION%
 
-[![License](https://img.shields.io/badge/License-BSD--like-lightgrey.svg)](https://github.com/caltechlibrary/%PROJECT_URLNAME%/LICENSE)
-[![Latest release](https://img.shields.io/github/v/release/caltechlibrary/%PROJECT_URLNAME%.svg?color=b44e88)](https://github.com/caltechlibrary/%PROJECT_URLNAME%/releases)
+[![License](https://img.shields.io/badge/License-BSD--like-lightgrey.svg)](https://github.com/caltechlibrary/%REPO_NAME%/LICENSE)
+[![Latest release](https://img.shields.io/github/v/release/caltechlibrary/%REPO_NAME%.svg?color=b44e88)](https://github.com/caltechlibrary/%REPO_NAME%/releases)
 
 
 ## Table of contents
@@ -21,7 +21,7 @@
 
 ## Introduction
 
-> _This README file is in Markdown format, and is meant to provide a template for README files as well an illustration of what the README file can be expected to look like.  For a software project, this [Introduction](#introduction) section &ndash; which you are presently reading &ndash; should provide background for the project, a brief explanation of what the project is about, and optionally, pointers to resources that can help orient readers.  Ideally, this section should be short._
+> _This README file is in Markdown format, and is meant to provide a template for README files as well an illustration of what the README file can be expected to look like.  For software, this [Introduction](#introduction) section &ndash; which you are presently reading &ndash; should provide background for the program, a brief explanation of what the project is about, and optionally, pointers to resources that can help orient readers.  Ideally, this section should be short._
 
 
 ## Installation
@@ -39,7 +39,7 @@
 >
 > _Begin with the simplest possible example of how to use your software.  Provide example command lines and/or screen images, as appropriate, to help readers understand how the software is expected to be used.  Many readers are likely to look for command lines they can copy-paste directly from your explanations, so it's best to keep that in mind as you write examples._
 >
-> _Some projects need to communicate additional information to users and can benefit from additional sections in the README file.  It's difficult to give specific instructions &ndash; a lot depends on your software, your intended audience, etc.  Use your judgment and ask for feedback from users or colleagues to help figure out what else is worth explaining._
+> _Some programs are complicated and users can benefit from additional sections in the README file.  It's difficult to give specific instructions &ndash; a lot depends on your software, your intended audience, etc.  Use your judgment and ask for feedback from users or colleagues to help figure out what else is worth explaining._
 
 
 ## Known issues and limitations
@@ -49,12 +49,12 @@
 
 ## Getting help
 
-If you find an issue, please submit it in [the GitHub issue tracker](https://github.com/caltechlibrary/%PROJECT_URLNAME%/issues) for this repository.
+If you find an issue, please submit it in [the GitHub issue tracker](https://github.com/caltechlibrary/%REPO_NAME%/issues) for this repository.
 
 
 ## Contributing
 
-Your help and participation in enhancing %PROJECT_NAME% is welcome!  Please visit the [guidelines for contributing](CONTRIBUTING.md) for some tips on getting started.
+Your help and participation in enhancing %REPO_NAME% is welcome!  Please visit the [guidelines for contributing](CONTRIBUTING.md) for some tips on getting started.
 
 
 ## License
@@ -64,7 +64,7 @@ Software produced by the Caltech Library is Copyright © %CREATION_YEAR% Califor
 
 ## Authors and history
 
-> _In this section, list the authors and contributors to your software project.  Adding additional notes here about the history of the project can make it more interesting and compelling.  This is also a place where you can acknowledge other contributions to the work and the use of other people's software or tools._
+> _In this section, list the authors and contributors to this software project.  Adding additional notes here about the history of the software and the overall project can make it more interesting and compelling.  This is also a place where you can acknowledge other contributions to the work and the use of other people's software or tools._
 
 
 ## Acknowledgments
@@ -74,6 +74,6 @@ This work was funded by the California Institute of Technology Library.
 <div align="center">
   <br>
   <a href="https://www.caltech.edu">
-    <img width="100" height="100" src="https://github.com/caltechlibrary/%PROJECT_URLNAME%/blob/main/.graphics/caltech-round.png">
+    <img width="100" height="100" src="https://github.com/caltechlibrary/%REPO_NAME%/blob/main/.graphics/caltech-round.png">
   </a>
 </div>
diff --git a/SUPPORT.md b/SUPPORT.md
@@ -3,6 +3,6 @@ Support
 
 Thank you for your interest in this project.  If you are experiencing problems or have questions, the following are the preferred methods of reaching someone:
 
-1. Report a new issue using the [issue tracker](https://github.com/caltechlibrary/%PROJECT_URLNAME%/issues).
+1. Report a new issue using the [issue tracker](https://github.com/caltechlibrary/%REPO_NAME%/issues).
 2. Send email to the Caltech Library: [helpdesk@library.caltech.edu](mailto:helpdesk@library.caltech.edu).
 3. Send email to an individual involved in the project. People's names appear in the top-level `README.md` file in the source code repository.
diff --git a/codemeta-TEMPLATE.json b/codemeta-TEMPLATE.json
@@ -1,11 +1,11 @@
 {
   "@context": "https://doi.org/10.5063/schema/codemeta-2.0",
   "@type": "SoftwareSourceCode",
-  "description": "%PROJECT_DESCRIPTION%",
-  "name": "%PROJECT_NAME%",
-  "codeRepository": "https://github.com/caltechlibrary/%PROJECT_URLNAME%",
-  "issueTracker": "https://github.com/caltechlibrary/%PROJECT_URLNAME%/issues",
-  "license": "https://github.com/caltechlibrary/%PROJECT_URLNAME%/blob/main/LICENSE",
+  "description": "%DESCRIPTION%",
+  "name": "%REPO_NAME%",
+  "codeRepository": "https://github.com/caltechlibrary/%REPO_NAME%",
+  "issueTracker": "https://github.com/caltechlibrary/%REPO_NAME%/issues",
+  "license": "https://github.com/caltechlibrary/%REPO_NAME%/blob/main/LICENSE",
   "version": "0.0.0",
   "author": [
     {
@@ -17,7 +17,7 @@
       "@id": "https://orcid.org/YOUR-ORCID"
     }],
   "developmentStatus": "active",
-  "downloadUrl": "https://github.com/caltechlibrary/%PROJECT_URLNAME%/archive/main.zip",
+  "downloadUrl": "https://github.com/caltechlibrary/%REPO_NAME%/archive/main.zip",
   "keywords": [
     "software",
     "science"
diff --git a/codemeta.json b/codemeta.json
@@ -42,8 +42,8 @@
         "python",
         "software"
     ],
-    "name": "Caltech Library Python Software Repository Template",
-    "description": "Template repository for software projects by the Caltech Library",
+    "name": "py-cli-template",
+    "description": "GitHub repository template for non-web Python programs",
     "version": "1.9.0",
     "maintainer": "https://orcid.org/0000-0001-9105-5960",
     "funder": {
diff --git a/module_name/__init__.py b/module_name/__init__.py
@@ -1,5 +1,5 @@
 '''
-__init__.py for %PROJECT_NAME%
+__init__.py for %MODULE_NAME%
 
 Copyright
 ---------
@@ -18,8 +18,8 @@
 #  ╰────────────────────── Notice ── Notice ── Notice ─────────────────────╯
 
 __version__     = '0.0.0'
-__description__ = '%PROJECT_DESCRIPTION%'
-__url__         = 'https://github.com/caltechlibrary/%PROJECT_URLNAME%'
+__description__ = '%DESCRIPTION%'
+__url__         = 'https://github.com/caltechlibrary/%REPO_NAME%'
 __author__      = '%AUTHOR_NAME%'
 __email__       = 'helpdesk@library.caltech.edu'
 __license__     = 'https://data.caltech.edu/license'
diff --git a/module_name/__main__.py b/module_name/__main__.py
@@ -1,5 +1,5 @@
 '''
-__main__.py: main function for %PROJECT_NAME%.
+__main__.py: main function for %MODULE_NAME%.
 
 Copyright
 ---------
@@ -11,7 +11,7 @@
 
 import sys
 if sys.version_info <= (3, 8):
-    print('%PROJECT_NAME% requires Python version 3.8 or higher,')
+    print('%MODULE_NAME% requires Python version 3.8 or higher,')
     print('but the current version of Python is ' + str(sys.version_info.major)
           + '.' + str(sys.version_info.minor) + '.')
     sys.exit(1)
@@ -30,7 +30,7 @@
     args       = 'arguments'
 )
 def main(version=False, debug='OUT', *args):
-    '''%PROJECT_DESCRIPTION%'''
+    '''%DESCRIPTION%'''
 
     # Set up debug logging as soon as possible, if requested ------------------
 
@@ -71,7 +71,7 @@ def print_version_info():
     # Precaution: add parent dir in case user is running from our source dir.
     from os import path
     sys.path.append(path.join(path.dirname(path.abspath(__file__)), '..'))
-    from %PROJECT_NAME% import print_version
+    from %MODULE_NAME% import print_version
     print_version()
 
 
@@ -85,7 +85,7 @@ def console_scripts_main():
     plac.call(main)
 
 
-# The following allows users to invoke this using "python3 -m %PROJECT_NAME%".
+# The following allows users to invoke this using "python3 -m %MODULE_NAME%".
 if __name__ == '__main__':
     # Print help if the user supplied no command-line arguments.
     if len(sys.argv) == 1 or (len(sys.argv) > 1 and sys.argv[1] == 'help'):
diff --git a/requirements-dev.txt b/requirements-dev.txt
@@ -1,9 +1,9 @@
 # =============================================================================
 # @file    requirements-dev.txt
-# @brief   Python dependencies for %PROJECT_URLNAME% for development & testing
+# @brief   Python dependencies for %REPO_NAME% for development & testing
 # @created %CREATION_DATE%
 # @license Please see the file named LICENSE in the project directory
-# @website https://github.com/caltechlibrary/%PROJECT_URLNAME%
+# @website https://github.com/caltechlibrary/%REPO_NAME%
 # =============================================================================
 
 -r requirements.txt
diff --git a/requirements.txt b/requirements.txt
@@ -1,9 +1,9 @@
 # =============================================================================
 # @file    requirements.txt
-# @brief   Python dependencies for %PROJECT_URLNAME%
+# @brief   Python dependencies for %REPO_NAME%
 # @created %CREATION_DATE%
 # @license Please see the file named LICENSE in the project directory
-# @website https://github.com/caltechlibrary/%PROJECT_URLNAME%
+# @website https://github.com/caltechlibrary/%REPO_NAME%
 # =============================================================================
 
 boltons
diff --git a/setup.cfg b/setup.cfg
diff --git a/setup.py b/setup.py
diff --git a/tests/test_cli.py b/tests/test_cli.py
diff --git a/tests/test_init.py b/tests/test_init.py

Original file line number	Diff line number	Diff line change
`@@ -3,7 +3,7 @@`
`3`	`3`	`# @brief Files and patterns for files and subdirs that git should ignore`
`4`	`4`	`# @date %CREATION_DATE%`
`5`	`5`	`# @license Please see the file named LICENSE in the project directory`
`6`		`-# @website https://github.com/caltechlibrary/%PROJECT_URLNAME%`
	`6`	`+# @website https://github.com/caltechlibrary/%REPO_NAME%`
`7`	`7`	`#`
`8`	`8`	`# The approach we suggest is to add ONLY project-specific rules here. Put`
`9`	`9`	`# rules that apply to your way of doing things (and the particular tools you`