feat(CHANGELOG): Add auto update opt to pkge #12 (#70)

Only a manually generated history file exists.

closes #12

cookiecutter.json

@@ -1,10 +1,11 @@
 {
-  "full_name": "Audrey Roy Greenfeld",
-  "email": "audreyr@example.com",
-  "github_username": "audreyr",
-  "project_name": "Python Boilerplate",
+  "full_name": "Mark Sevelj",
+  "email": "mark@example.com",
+  "github_username": "imAsparky",
+  "project_name": "Python 3 Package Boilerplate",
+  "git_project_name": "{{ cookiecutter.project_name.lower().replace(' ', '-').replace('_', '-') }}",
   "project_slug": "{{ cookiecutter.project_name.lower().replace(' ', '_').replace('-', '_') }}",
-  "project_short_description": "Python Boilerplate contains all the boilerplate you need to create a Python package.",
+  "project_short_description": "Python 3 Package Boilerplate contains all the boilerplate you need to create a Python package.",
   "pypi_username": "{{ cookiecutter.github_username }}",
   "version": "0.1.0",
   "use_pytest": "n",
@@ -13,5 +14,7 @@
   "command_line_interface": ["Click", "Argparse", "No command-line interface"],
   "create_author_file": "y",
   "create_conventional_commits_edit_message": "y",
+  "create_auto_CHANGELOG": "y",
+  "github_access_token": ["secrets.GITHUB_TOKEN", "secrets.CHANGELOG_UPDATE"],
   "open_source_license": ["MIT license", "BSD license", "ISC license", "Apache Software License 2.0", "GNU General Public License v3", "Not open source"]
 }

docs/source/prompts.rst

@@ -26,6 +26,15 @@ project_name
 The name of your new Python package project. This is used in documentation,
 so spaces and any characters are fine here.
 
+git_project_name
+~~~~~~~~~~~~~~~~
+The name of the GitHub project repository you have created.
+
+If it is the same as your project_name but with hyphens instead of spaces leave
+this blank.  Your GitHub repository name will be generated with hyphens.
+
+If its different enter your project GitHub repository name here.
+
 project_slug
 ~~~~~~~~~~~~
 The namespace of your Python package. This should be Python import-friendly.
@@ -67,9 +76,13 @@ project.
     Whether to create an authors file.
 
 **create_conventional_commits_edit_message**
-    Whether to use a commit message that helps you adhere to the
-    `Conventional Commits <https://www.conventionalcommits.org/en/v1.0.0/>`_
-    specification.
+   Whether to use a commit message that helps you adhere to the
+   `Conventional Commits <https://www.conventionalcommits.org/en/v1.0.0/>`_
+   specification.
+
+   If you plan to use the create_auto_CHANGELOG feature, this template will
+   help you keep your messages in the correct format for the auto CHANGELOG
+   feature.
 
 .. important::
 
@@ -80,6 +93,25 @@ project.
 
         git config --local commit.template .github/.git-commit-template.txt
 
+**create_auto_CHANGELOG**
+   create_auto_CHANGELOG will use GitHub actions to generate a changelog using
+   a cron job, scheduled daily.
+
+**github_access_token**
+  For new or small repositories, select `secrets.GITHUB_TOKEN`.
+  This is adequate for most small packages.
+
+  For larger repositories, the `GITHUB_TOKEN` may error on the rate limit when
+  generating the CHANGELOG.   If so you will need a PAT so
+  select `secrets.CHANGELOG_UPDATE`.
+
+  After generating your GitHub PAT, ensure you use `CHANGELOG_UPDATE` as the
+  repository secret name.  Be careful not to share the secret or commit it to
+  the repository accidentally.
+
+  See `Encrypted Secrets <https://docs.github.com/en/actions/reference/encrypted-secrets>`_
+  for more information on generating secrets and repository security.
+
 **open_source_license**
     Choose a `license <https://choosealicense.com/>`_. Options:
 

docs/source/tutorial.rst

@@ -15,12 +15,53 @@ top of the page at `GitHub Help`_.
 .. _`GitHub account`: https://github.com/
 .. _`GitHub Help`: https://help.github.com/
 
+Step 1: Create a GitHub Repo
+----------------------------
+
+We do this step first to make sure that your new package name is available.
+
+Your GitHub package name can use a hyphen -, however, the module name must use
+an underscore _.
+
+Don't worry; we have your back; go right ahead if you would like to use hyphens
+in your package name.  We generate your module names correctly using
+underscores from the information gathered when you cookiecutter your new
+project.
+
+.. todo::
+
+    #. Fix the git repo bash commands in Step 1 of the tutorial.
+    #. The git bash commands may be better lower down the list as well.
+
+    See `Issue 69 <https://github.com/imAsparky/cookiecutter-py3-package/issues/69>`_.
+
+.. code-block:: bash
+
+    cd mypackage
+    git init .
+    git add .
+    git config --local commit.template .github/.git-commit-template.txt
+    git commit -m "Initial skeleton."
+    git remote add origin git@github.com:myusername/mypackage.git
+    git push -u origin main
+
+Where ``myusername`` and ``mypackage`` are adjusted for your username and
+package name.
+
+You will need an ssh key to push local changes to your repository.
+
+You can `Generate`_ a new key or `Add`_ an existing one.
 
-Step 1: Install Cookiecutter
+.. _`Generate`: https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/
+.. _`Add`: https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/
+
+
+Step 2: Install Cookiecutter
 ----------------------------
 
 First, you need to create and activate a virtualenv for the package project.
-Use your favorite method, or create a virtualenv for your new package like this:
+Use your favourite method, or create a virtualenv for your new package
+like this:
 
 .. code-block:: bash
 
@@ -34,8 +75,14 @@ Activate your environment:
 
     source bin/activate
 
+or use the . source shortcut like this
+
+.. code-block:: bash
+
+    . bin/activate
+
 On Windows, activate it like this. You may find that using a Command Prompt
-window works better than gitbash.
+Terminal works better than gitbash.
 
 .. code-block:: powershell
 
@@ -49,59 +96,29 @@ Install cookiecutter:
     pip install cookiecutter
 
 
-Step 2: Generate Your Package
+Step 3 : Generate Your Package
 -----------------------------
 
 Now it's time to generate your Python package.
 
-Use cookiecutter, pointing it at the cookiecutter-py3-package repo:
+Use cookiecutter, pointing it to the cookiecutter-py3-package repository:
 
 .. code-block:: bash
 
     cookiecutter https://github.com/imAsparky/cookiecutter-py3-package.git
 
-You'll be asked to enter a bunch of values to set the package up.
-If you don't know what to enter, stick with the defaults.
-
-
-Step 3: Create a GitHub Repo
-----------------------------
-
-Go to your GitHub account and create a new repo named ``mypackage``, where
-``mypackage`` matches the ``[project_slug]`` from your answers to running
-cookiecutter. This is so that Travis CI and pyup.io can find it when we get
-to Step 5.
-
-``If your virtualenv folder is within your project folder, be sure to add the
-virtualenv folder name to your .gitignore file.``
-
-You will find one folder named after the ``[project_slug]``. Move into this
-folder, and then setup git to use your GitHub repo and upload the code:
-
-.. code-block:: bash
-
-    cd mypackage
-    git init .
-    git add .
-    git config --local commit.template .github/.git-commit-template.txt
-    git commit -m "Initial skeleton."
-    git remote add origin git@github.com:myusername/mypackage.git
-    git push -u origin main
-
-Where ``myusername`` and ``mypackage`` are adjusted for your username and package name.
+Cookiecutter will ask questions to set your package up.
+If you're unsure or don't know what to enter, stick with the defaults.
 
-You'll need a ssh key to push the repo. You can `Generate`_ a key or `Add`_ an existing one.
-
-.. _`Generate`: https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/
-.. _`Add`: https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/
 
 
 Step 4: Install Dev Requirements
 --------------------------------
 
-You should still be in the folder containing the ``requirements_dev.txt`` file.
+You should still be in the root folder, the one containing the
+``requirements_dev.txt`` file.
 
-Your virtualenv should still be activated. If it isn't, activate it now.
+Check your virtualenv is still activated. If it isn't, activate it now.
 Install the new project's local development requirements:
 
 .. code-block:: bash
@@ -149,7 +166,7 @@ Install the new project's local development requirements:
 Step 5: Set Up Read the Docs
 ----------------------------
 
-`Read the Docs`_ hosts documentation for the open source community. Think of it
+`Read the Docs`_ hosts documentation for the open-source community. Think of it
 as Continuous Documentation.
 
 Log into your account at `Read the Docs`_ . If you don't have one, create one
@@ -162,6 +179,7 @@ repository and follow the directions.
 Now your documentation will get rebuilt when you make documentation changes to
 your package.
 
+
 .. _`Read the Docs`: https://readthedocs.org/
 
 Step 6: Set Up pyup.io
@@ -177,11 +195,19 @@ Click on the green ``Add Repo`` button in the top left corner and select the
 repo you created in Step 3. A popup will ask you whether you want to pin your
 dependencies. Click on ``Pin`` to add the repo.
 
-Once your repo is set up correctly, the pyup.io badge will show your current
+When your repository is correctly set up, the pyup.io badge will show your current
 update status.
 
+
 .. _`pyup.io`: https://pyup.io/
 
+
+.. todo::
+
+    Add a tutorial to describe using Test Pypi.
+
+    See `Issue 13 <https://github.com/imAsparky/cookiecutter-py3-package/issues/13>`_.
+
 Step 7: Release on PyPI
 -----------------------
 

hooks/post_gen_project.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-"""cookiecutter-p3-package post package generation jobs."""
+"""cookiecutter-py3-package post package generation jobs."""
 import os
 
 PROJECT_DIRECTORY = os.path.realpath(os.path.curdir)
@@ -25,3 +25,10 @@ def remove_file(filepath):
 
     if "{{ cookiecutter.create_conventional_commits_edit_message }}" != "y":
         remove_file(".github/.git-commit-template.txt")
+
+    if "{{ cookiecutter.create_auto_CHANGELOG }}" != "y":
+        remove_file("CHANGELOG.md")
+        remove_file(".github/workflows/update-changelog.yaml")
+
+    if "{{ cookiecutter.create_auto_CHANGELOG }}" == "y":
+        remove_file("HISTORY.rst")

hooks/pre_gen_project.py

@@ -9,9 +9,8 @@
 
 if not re.match(MODULE_REGEX, MODULE_NAME):
     print(
-        "ERROR: The project slug (%s) is not a valid Python module name.\
-        Please do not use a - and use _ instead"
-        % MODULE_NAME
+        f"ERROR: The project slug {MODULE_NAME} is not a valid Python module\
+            name.  Please do not use a - and use _ instead"
     )
 
     # Exit to cancel project