Renaming github_username to github_owner + generating __repo_name & __repo_url (#409)

matt-graham · paddyroddy · dstansby · web-flow · commit 85b0b29f73d4 · 2024-11-05T14:02:50.000Z
Though its not exposed to user now we have longer prompts rather than using variable names directly, I think `github_username` is a bit of a misnomer given that it can be either a user or organization name, hence I think `github_owner` would be a better choice. We also currently manually construct the GitHub repository URL in lots of different bits of the template and also the qualified repository name in a few places. We can use [double underscore prefixed (rendered) private variables](https://cookiecutter.readthedocs.io/en/stable/advanced/private_variables.html) in the cookiecutter config to generate the repository URL and qualified name once and then reuse elsewhere to avoid the repetition. This would also make it simpler to later switch to supporting alternative repository hosting options such as GitLab in future (which is the rational for naming the variables `__repo_name` and `__repo_url` rather than `__github_repo_name` and `__github_repo_url`). --------- Co-authored-by: Patrick J. Roddy <patrickjamesroddy@gmail.com> Co-authored-by: David Stansby <dstansby@gmail.com>
diff --git a/cookiecutter.json b/cookiecutter.json
@@ -8,11 +8,13 @@
   "project_short_description": "A cookiecutter package with UCL ARC recommendations.",
   "initialise_git_repository": true,
   "deploy_docs_to_github_pages": true,
-  "github_username": "{{cookiecutter.author_given_names.lower().replace(' ', '-')}}-{{cookiecutter.author_family_names.lower().replace(' ', '-')}}",
+  "github_owner": "{{cookiecutter.author_given_names.lower().replace(' ', '-')}}-{{cookiecutter.author_family_names.lower().replace(' ', '-')}}",
   "min_python_version": ["3.11", "3.12", "3.13"],
   "max_python_version": ["3.13", "3.12", "3.11"],
   "license": ["MIT", "BSD-3", "GPL-3.0"],
   "funder": "",
+  "__repo_name": "{{cookiecutter.github_owner}}/{{cookiecutter.project_slug}}",
+  "__repo_url": "https://github.com/{{cookiecutter.__repo_name}}",
   "__prompts__": {
     "author_given_names": "Given name(s) of package author",
     "author_family_names": "Family name(s) of package author",
@@ -23,7 +25,7 @@
     "project_short_description": "Short description of the project",
     "initialise_git_repository": "Initialise project directory as a Git repository?",
     "deploy_docs_to_github_pages": "Automatically deploy HTML docs to GitHub Pages on pushes to main?",
-    "github_username": "GitHub user or organization name which will be owner of repository",
+    "github_owner": "GitHub user or organization name which will be owner of repository",
     "min_python_version": "Minimum Python version supported by package",
     "max_python_version": "Maximum Python version supported by package",
     "license": "Which open-source license to release package under",
diff --git a/hooks/post_gen_project.py b/hooks/post_gen_project.py
@@ -62,7 +62,7 @@ def main(initialise_git_repository: str, deploy_docs_to_github_pages: str) -> in
             print(
                 "GitHub CLI detected, you can create a repo with the following:\n\n"
                 "gh repo create "
-                "{{cookiecutter.github_username}}/{{cookiecutter.project_slug}} "
+                "{{cookiecutter.__repo_name}} "
                 '-d "{{cookiecutter.project_short_description}}" '
                 "--public "
                 "-r origin "
@@ -73,12 +73,12 @@ def main(initialise_git_repository: str, deploy_docs_to_github_pages: str) -> in
             print(
                 "You now have a local git repository. To sync this to GitHub "
                 "you need to create an empty GitHub repo with the name "
-                "{{cookiecutter.github_username}}/{{cookiecutter.project_slug}} "
+                "{{cookiecutter.__repo_name}} "
                 "- DO NOT SELECT ANY OTHER OPTION.\n\nSee this link for more detail "
                 "https://docs.github.com/en/get-started/quickstart/create-a-repo.\n\n"
                 "Then run:\n\n"
                 "git remote add origin git@github.com:"
-                "{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}.git\n"
+                "{{cookiecutter.__repo_name}}.git\n"
             )
         except subprocess.CalledProcessError as e:
             # some other error
@@ -91,13 +91,11 @@ def main(initialise_git_repository: str, deploy_docs_to_github_pages: str) -> in
             "deploying as a GitHub Pages website. To allow the GitHub Actions bot to "
             "push to the gh-pages branch you need to enable 'Read and write "
             "permissions' under 'Workflow permissions' at\n\n"
-            "https://github.com/{{cookiecutter.github_username}}/"
-            "{{cookiecutter.project_slug}}/settings/actions\n\n"
+            "{{cookiecutter.__repo_url}}/settings/actions\n\n"
             "After the 'Documentation' workflow has successfully completed at least "
             "once you will also need to configure the repository to deploy a GitHub "
             "pages site from the content on the gh-pages branch by going to\n\n"
-            "https://github.com/{{cookiecutter.github_username}}/"
-            "{{cookiecutter.project_slug}}/settings/pages\n\n"
+            "{{cookiecutter.__repo_url}}/settings/pages\n\n"
             "and under 'Built and deployment' selecting 'Deploy from a branch' for "
             "the 'Source' drop-down and 'gh-pages' for the 'Branch' drop-down, "
             "leaving the branch path drop-down with its default value of '/ (root)'."
diff --git a/tests/test_git_init.py b/tests/test_git_init.py
@@ -15,7 +15,7 @@ def test_initialisation_of_git_repo(
 ) -> None:
     """Checks to see if git was correctly initialised if desired."""
     test_config = {
-        "github_username": "test-user",
+        "github_owner": "test-user",
         "project_short_description": "description",
         "project_name": "Cookiecutter Test",
         "initialise_git_repository": initialise_git_repository,
@@ -57,7 +57,7 @@ def test_initialisation_of_git_repo(
         )
         assert (
             "GitHub CLI detected, you can create a repo with the following:\n\n"
-            f"gh repo create {test_config['github_username']}/"
+            f"gh repo create {test_config['github_owner']}/"
             f"cookiecutter-test -d "
             f"\"{test_config['project_short_description']}\" --public -r "
             f"origin --source cookiecutter-test" in result.stdout
@@ -69,11 +69,11 @@ def test_initialisation_of_git_repo(
         assert (
             "You now have a local git repository. To sync this to GitHub you "
             "need to create an empty GitHub repo with the name "
-            f"{test_config['github_username']}/"
+            f"{test_config['github_owner']}/"
             f"cookiecutter-test - DO NOT SELECT ANY "
             "OTHER OPTION.\n\nSee this link for more detail "
             "https://docs.github.com/en/get-started/quickstart/create-a-repo"
             ".\n\nThen run:\n\ngit remote add origin git@github.com:"
-            f"{test_config['github_username']}/"
+            f"{test_config['github_owner']}/"
             f"cookiecutter-test.git" in result.stdout
         )
diff --git a/tests/test_package_generation.py b/tests/test_package_generation.py
@@ -40,7 +40,7 @@ def test_package_generation(
 ) -> None:
     """Test package generation."""
     test_config = {
-        "github_username": "test-user",
+        "github_owner": "test-user",
         "project_short_description": "description",
         "project_name": "Cookiecutter Test",
         # Not having a git repo makes it easier to check in/out reference
@@ -98,7 +98,7 @@ def test_pip_installable(
 ) -> None:
     """Test generated package is pip installable."""
     test_config = {
-        "github_username": "test-user",
+        "github_owner": "test-user",
         "project_short_description": "description",
         "project_name": "Cookiecutter Test",
     }
@@ -129,7 +129,7 @@ def test_optional_funder(
 ) -> None:
     """Test package generation."""
     config = {
-        "github_username": "test-user",
+        "github_owner": "test-user",
         "project_short_description": "description",
         "project_name": "Cookiecutter Test",
         "funder": funder,
diff --git a/tutorial.md b/tutorial.md
@@ -153,19 +153,19 @@ When you completed setting up the package using the `cookiecutter` command you s
 ```sh
 GitHub CLI detected, you can create a repo with the following:
 
-gh repo create {github_user}/{project_slug} -d "{project_description}" --public -r origin --source {project_slug}
+gh repo create {github_owner}/{project_slug} -d "{project_description}" --public -r origin --source {project_slug}
 ```
 
-where `{github_user}`, `{project_slug}` and `{project_description}` are replaced with the relevant GitHub user name, project slug and description that you entered when setting up the package using `cookiecutter`. You should now copy-paste and run the `gh repo create ...` command that was printed out in the message - if you no longer have access to the message you can use the example above, being careful to subsitute the placeholders in braces `{}` with the relevant values.
+where `{github_owner}`, `{project_slug}` and `{project_description}` are replaced with the relevant GitHub repository owner (user name), project slug and description that you entered when setting up the package using `cookiecutter`. You should now copy-paste and run the `gh repo create ...` command that was printed out in the message - if you no longer have access to the message you can use the example above, being careful to subsitute the placeholders in braces `{}` with the relevant values.
 
 If you get an error message at this point it may be because you have not installed the GitHub CLI or set up the authorisation for the GitHub CLI as [described in the setup instructions above](#%EF%B8%8F-setting-up-dependencies-for-using-template).
 
 If the command runs successfully you should see a message of the form
 
 ```sh
-✓ Created repository {github_user}/{project_slug} on GitHub
-  https://github.com/{github_user}/{project_slug}
-✓ Added remote https://github.com/{github_user}/{project_slug}.git
+✓ Created repository {github_owner}/{project_slug} on GitHub
+  https://github.com/{github_owner}/{project_slug}
+✓ Added remote https://github.com/{github_owner}/{project_slug}.git
 ```
 
 A repository should have been created at the printed URL which you should be able to navigate to in your browser (either copy-paste in to browser or depending on terminal application you may be able to hold `Ctrl` and click on URL directly). Currently both the remote and local repositories are empty as we have not made any commits.
@@ -181,7 +181,7 @@ git push --set-upstream origin main
 
 If you now navigate to the GitHub repository URL in your browser you should see the package files present, with the content of the top-level `README.md` being displayed as the repository landing page.
 
-The push of the initial commit to the default `main` branch will have also triggered runs of the GitHub Actions workflows set up in the repository. You can view the status of the workflow job runs by opening the `Actions` pane from the top navigation bar on the repository landing page, or going to the URL `https://github.com/{github_user}/{project_slug}/actions`.
+The push of the initial commit to the default `main` branch will have also triggered runs of the GitHub Actions workflows set up in the repository. You can view the status of the workflow job runs by opening the `Actions` pane from the top navigation bar on the repository landing page, or going to the URL `https://github.com/{github_owner}/{project_slug}/actions`.
 
 Depending on your account settings, you may find that the `Documentation` workflow shows as failed (❌). If this is the case this is likely because the repository has been set by default to only allow GitHub Actions workflows read permissions on the repository, which prevents the step in the `Documentation` workflow which pushes the built HTML documentation to a branch `gh-pages` from completing. In the next section we will look at how to configure the repository to ensure the permissions are set correctly and have the HTML documentation deployed to a GitHub Pages website.
 
@@ -196,27 +196,27 @@ GitHub Pages website. To allow the GitHub Actions bot to push to the gh-pages
 branch you need to enable 'Read and write permissions' under 'Workflow
 permissions' at
 
-https://github.com/{github_user}/{project_slug}/settings/actions
+https://github.com/{github_owner}/{project_slug}/settings/actions
 
 After the 'Documentation' workflow has successfully completed at least once
 you will also need to configure the repository to deploy a GitHub pages site
 from the content on the gh-pages branch by going to
 
-https://github.com/{github_user}/{project_slug}/settings/pages
+https://github.com/{github_owner}/{project_slug}/settings/pages
 
 and under 'Built and deployment' selecting 'Deploy from a branch' for the
 'Source' drop-down and 'gh-pages' for the 'Branch' drop-down, leaving the
 branch path drop-down with its default value of '/ (root)'.
 ```
 
-where as before `{github_user}` and `{project_slug}` are replaced with the relevant GitHub user name and project slug that you entered when setting up the package.
+where as before `{github_owner}` and `{project_slug}` are replaced with the relevant GitHub repository owner and project slug that you entered when setting up the package.
 
-The first part of the instructions gives details of how to set the permissions for GitHub Actions workflows in the repository to allow the GitHub Actions bot to push the built HTML documentation to a branch `gh-pages` on updates to the default `main` branch on the repository, so that the documentation is automatically updated whenever changes are merged in to `main`. After going to the Actions settings page at the URL indicated (which can also be reached by going to the `Settings` tab in the top navigation bar of the repository and then selecting `Action > General` in the left hand navigation menu) and ensuring `Workflow permissions` is set to allow `Read and write permissions`, if you have changed the permissions you will also need to re-run the documentation workflow with the updated permissions. This can be done by going to the Actions pane in the repository (accessible from top navigation bar or by going to `https://github.com/{github_user}/{project_slug}/actions`), clicking on the (top / latest if there are multiple) entry for the _Documentation_ workflow, which should be showing as failing, and then from the resulting page click the `Re-run all jobs` button.
+The first part of the instructions gives details of how to set the permissions for GitHub Actions workflows in the repository to allow the GitHub Actions bot to push the built HTML documentation to a branch `gh-pages` on updates to the default `main` branch on the repository, so that the documentation is automatically updated whenever changes are merged in to `main`. After going to the Actions settings page at the URL indicated (which can also be reached by going to the `Settings` tab in the top navigation bar of the repository and then selecting `Action > General` in the left hand navigation menu) and ensuring `Workflow permissions` is set to allow `Read and write permissions`, if you have changed the permissions you will also need to re-run the documentation workflow with the updated permissions. This can be done by going to the Actions pane in the repository (accessible from top navigation bar or by going to `https://github.com/{github_owner}/{project_slug}/actions`), clicking on the (top / latest if there are multiple) entry for the _Documentation_ workflow, which should be showing as failing, and then from the resulting page click the `Re-run all jobs` button.
 
-Once the _Documentation_ workflow has successfully completed, a new branch `gh-pages` should have been created in the repository containing the HTML documentation. The second part of the instructions printed in the message output by the `cookiecutter` command indicate to go to a URL `https://github.com/{github_user}/{project_slug}/settings/pages` to set this branch as the source for a GitHub Pages website for the repository. If you now follow those instructions, setting the `Source` to `Deploy from branch` and `Branch` to `gh-pages`, the a new Actions workflow `pages-build-deployment` will be automatically triggered. Once this workflow has completed, you should be able to view the HTML documentation for the repository at a URL
+Once the _Documentation_ workflow has successfully completed, a new branch `gh-pages` should have been created in the repository containing the HTML documentation. The second part of the instructions printed in the message output by the `cookiecutter` command indicate to go to a URL `https://github.com/{github_owner}/{project_slug}/settings/pages` to set this branch as the source for a GitHub Pages website for the repository. If you now follow those instructions, setting the `Source` to `Deploy from branch` and `Branch` to `gh-pages`, the a new Actions workflow `pages-build-deployment` will be automatically triggered. Once this workflow has completed, you should be able to view the HTML documentation for the repository at a URL
 
 ```sh
-https://{github_user}.github.io/{project_slug}
+https://{github_owner}.github.io/{project_slug}
 ```
 
 The index page of the documentation reproduces the content from the repository README file. The documentation site also importantly includes _application programming interface_ (API) reference documentation built from the [docstrings](https://peps.python.org/pep-0257/#what-is-a-docstring) in the package source code; this API documentation is accessible from the `API reference` link in the navigation.
diff --git a/{{cookiecutter.project_slug}}/CITATION.cff b/{{cookiecutter.project_slug}}/CITATION.cff
@@ -5,6 +5,6 @@ authors:
   - family-names: "{{cookiecutter.author_family_names }}"
     given-names: "{{ cookiecutter.author_given_names }}"
     email: "{{ cookiecutter.author_email }}"
-repository-code: "https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}"
+repository-code: "{{ cookiecutter.__repo_url }}"
 title: "{{ cookiecutter.project_name }}: {{ cookiecutter.project_short_description }}"
 license: "{{ cookiecutter.license }}"
diff --git a/{{cookiecutter.project_slug}}/README.md b/{{cookiecutter.project_slug}}/README.md
@@ -7,12 +7,12 @@
 [![License][license-badge]](./LICENSE.md)
 
 <!-- prettier-ignore-start -->
-[tests-badge]:              https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}/actions/workflows/tests.yml/badge.svg
-[tests-link]:               https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}/actions/workflows/tests.yml
-[linting-badge]:            https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}/actions/workflows/linting.yml/badge.svg
-[linting-link]:             https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}/actions/workflows/linting.yml
-[documentation-badge]:      https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}/actions/workflows/docs.yml/badge.svg
-[documentation-link]:       https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}/actions/workflows/docs.yml
+[tests-badge]:              {{cookiecutter.__repo_url}}/actions/workflows/tests.yml/badge.svg
+[tests-link]:               {{cookiecutter.__repo_url}}/actions/workflows/tests.yml
+[linting-badge]:            {{cookiecutter.__repo_url}}/actions/workflows/linting.yml/badge.svg
+[linting-link]:             {{cookiecutter.__repo_url}}/actions/workflows/linting.yml
+[documentation-badge]:      {{cookiecutter.__repo_url}}/actions/workflows/docs.yml/badge.svg
+[documentation-link]:       {{cookiecutter.__repo_url}}/actions/workflows/docs.yml
 {%- if cookiecutter.license == "MIT" %}
 [license-badge]:            https://img.shields.io/badge/License-MIT-yellow.svg
 {%- elif cookiecutter.license == "BSD-3" %}
@@ -68,13 +68,13 @@ development version of `{{cookiecutter.project_slug}}` using `pip` in the curren
 environment run
 
 ```sh
-pip install git+https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}.git
+pip install git+{{cookiecutter.__repo_url}}.git
 ```
 
 Alternatively create a local clone of the repository with
 
 ```sh
-git clone https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}.git
+git clone {{cookiecutter.__repo_url}}.git
 ```
 
 and then install in editable mode by running
diff --git a/{{cookiecutter.project_slug}}/mkdocs.yml b/{{cookiecutter.project_slug}}/mkdocs.yml
@@ -2,8 +2,8 @@ site_name: "{{cookiecutter.project_name}}"
 site_description: "Documentation website for {{cookiecutter.project_name}}"
 site_author: "{{cookiecutter.author_given_names}} {{cookiecutter.author_family_names}}"
 copyright: "Copyright © {% now 'utc', '%Y' %} {{cookiecutter.author_given_names}} {{cookiecutter.author_family_names}}"
-repo_url: "https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}/"
-repo_name: "{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}"
+repo_url: "{{cookiecutter.__repo_url}}/"
+repo_name: "{{cookiecutter.__repo_name}}"
 edit_uri: edit/main/docs/
 
 validation:
@@ -60,4 +60,4 @@ plugins:
 extra:
   social:
     - icon: fontawesome/brands/github
-      link: "https://github.com/{{cookiecutter.github_username}}"
+      link: "https://github.com/{{cookiecutter.github_owner}}"
diff --git a/{{cookiecutter.project_slug}}/pyproject.toml b/{{cookiecutter.project_slug}}/pyproject.toml
@@ -50,7 +50,7 @@ optional-dependencies = {dev = [
 readme = "README.md"
 requires-python = ">={{cookiecutter.min_python_version}}"
 license.file = "LICENSE.md"
-urls.homepage = "https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}"
+urls.homepage = "{{cookiecutter.__repo_url}}"
 
 [tool.coverage]
 report = {sort = "cover"}
