Merge branch 'master' of https://github.com/choldgraf/github-activity

Author: choldgraf

.gitignore

@@ -102,3 +102,6 @@ venv.bak/
 
 # mypy
 .mypy_cache/
+
+# Docs tmp files
+docs/tags_list.txt

docs/conf.py

@@ -17,38 +17,62 @@
 
 # -- Project information -----------------------------------------------------
 
-project = 'GitHub Activity'
-copyright = '2020, Chris Holdgraf'
-author = 'Chris Holdgraf'
+project = "GitHub Activity"
+copyright = "2020, Chris Holdgraf"
+author = "Chris Holdgraf"
 
 
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = [
-    "myst_parser"
-]
+extensions = ["myst_parser"]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_book_theme'
+html_theme = "sphinx_book_theme"
 html_theme_options = {"single_page": True}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ["_static"]
+
+# Add a table of the supported PR types, tags, etc
+from github_activity.github_activity import TAGS_METADATA_BASE
+
+table_content = []
+for key, vals in TAGS_METADATA_BASE.items():
+    cont = [
+        key,
+        " ".join(vals["tags"]),
+        " ".join(vals["pre"]),
+        f'"{vals["description"]}"',
+    ]
+    table_content.append(", ".join(cont))
+
+table_content = "\n".join(table_content)
+table_template = f"""
+```{{csv-table}} List of PR types
+:header: PR type, Tags, Prefix, Description
+
+{table_content}
+```
+"""
+
+from pathlib import Path
+
+Path("./tags_list.txt").write_text(table_template)

docs/index.md

@@ -22,7 +22,7 @@ The easiest way to install this package is to do so directly from GitHub with `p
 pip install git+https://github.com/choldgraf/github-activity
 ```
 
-## Usage
+## Generate a markdown changelog
 
 The easiest way to use `github-activity` to generate activity markdown is to use
 the command-line interface. It takes the following form:
@@ -50,6 +50,28 @@ github-activity jupyter/notebook -s 6.0.0 -u 6.0.1 -o sample_notebook_activity.m
 
 You can find the [resulting markdown here](sample_notebook_activity).
 
+### Splitting PRs by tags and prefixes
+
+Often you wish to split your PRs into multiple categories so that they are easier
+to scan and parse. You may also *only* want to keep some PRs (e.g. features, or API
+changes) while excluding others from your changelog.
+
+`github-activity` uses the GitHub tags as well as PR prefixes to automatically
+categorize each PR and display it in a section in your markdown. It roughly
+follows the [keepachangelog taxonomy of changes](https://keepachangelog.com/en/1.0.0/).
+
+Below is a list of the supported PR types, as well as the tags / title prefixes
+that will be used to identify the right category.
+
+```{include} tags_list.txt
+```
+
+```{tip}
+You can choose to *remove* some types of PRs from your changelog by passing the
+`--tags` parameter in the CLI. This is a list of a subset of names taken from the
+left-most column above.
+```
+
 ### Using a GitHub API token
 
 `github-activity` uses the GitHub API to pull information about a repository's activity.
@@ -89,4 +111,4 @@ contributor is anyone who has:
 * Commented on >= 2 issues that weren't theirs
 * Commented >= 6 times on any one issue
 
-We'd love feedback on whether this is a good set of rules to use.
+We'd love feedback on whether this is a good set of rules to use.

github_activity/github_activity.py

@@ -14,20 +14,41 @@
 
 # The tags and description to use in creating subsets of PRs
 TAGS_METADATA_BASE = {
+    "new": {
+        "tags": ["feature", "new"],
+        "pre": ["NEW", "FEAT", "FEATURE"],
+        "description": "New features added",
+    },
     "enhancement": {
-        "tags": ["enhancement", "feature", "enhancements"],
+        "tags": ["enhancement", "enhancements"],
+        "pre": ["NEW", "ENH", "ENHANCEMENT", "IMPROVE"],
         "description": "Enhancements made",
     },
-    "bug": {"tags": ["bug", "bugfix", "bugs"], "description": "Bugs fixed",},
+    "bug": {
+        "tags": ["bug", "bugfix", "bugs"],
+        "pre": ["FIX", "BUG"],
+        "description": "Bugs fixed",
+    },
     "maintenance": {
         "tags": ["maintenance", "maint"],
+        "pre": ["MAINT", "MNT"],
         "description": "Maintenance and upkeep improvements",
     },
     "documentation": {
         "tags": ["documentation", "docs", "doc"],
+        "pre": ["DOC", "DOCS"],
         "description": "Documentation improvements",
     },
-    "api_change": {"tags": ["api-change", "apichange"], "description": "API Changes",},
+    "api_change": {
+        "tags": ["api-change", "apichange"],
+        "pre": ["BREAK", "BREAKING", "BRK", "UPGRADE"],
+        "description": "API and Breaking Changes",
+    },
+    "deprecate": {
+        "tags": ["deprecation", "deprecate"],
+        "pre": ["DEPRECATE", "DEPRECATION", "DEP"],
+        "description": "Deprecated features",
+    },
 }
 
 
@@ -273,9 +294,16 @@ def generate_activity_md(
 
     # Separate out items by their tag types
     for kind, kindmeta in tags_metadata.items():
+        # First find the PRs based on tag
         mask = closed_prs["labels"].map(
             lambda a: any(ii in jj for ii in kindmeta["tags"] for jj in a)
         )
+        # Now find PRs based on prefix
+        mask_pre = closed_prs["title"].map(
+            lambda title: any(f"{ipre}:" in title for ipre in kindmeta["pre"])
+        )
+        mask = mask | mask_pre
+
         kindmeta["data"] = closed_prs.loc[mask]
         kindmeta["mask"] = mask
 

github_activity/tags.yaml

@@ -0,0 +1,64 @@
+api_change:
+  description: API and Breaking Changes
+  pre:
+  - BREAK
+  - BREAKING
+  - BRK
+  - UPGRADE
+  tags:
+  - api-change
+  - apichange
+bug:
+  description: Bugs fixed
+  pre:
+  - FIX
+  - BUG
+  tags:
+  - bug
+  - bugfix
+  - bugs
+deprecate:
+  description: Deprecated features
+  pre:
+  - DEPRECATE
+  - DEPRECATION
+  - DEP
+  tags:
+  - deprecation
+  - deprecate
+documentation:
+  description: Documentation improvements
+  pre:
+  - DOC
+  - DOCS
+  tags:
+  - documentation
+  - docs
+  - doc
+enhancement:
+  description: Enhancements made
+  pre:
+  - NEW
+  - ENH
+  - ENHANCEMENT
+  - IMPROVE
+  tags:
+  - enhancement
+  - enhancements
+maintenance:
+  description: Maintenance and upkeep improvements
+  pre:
+  - MAINT
+  - MNT
+  tags:
+  - maintenance
+  - maint
+new:
+  description: New features added
+  pre:
+  - NEW
+  - FEAT
+  - FEATURE
+  tags:
+  - feature
+  - new

setup.py

@@ -4,7 +4,7 @@
 from glob import glob
 from pathlib import Path
 
-init = Path().joinpath('github_activity', '__init__.py')
+init = Path().joinpath("github_activity", "__init__.py")
 for line in init.read_text().split("\n"):
     if line.startswith("__version__ ="):
         version = line.split(" = ")[-1].strip('"')
@@ -33,5 +33,8 @@
     use_package_data=True,
     entry_points={"console_scripts": ["github-activity = github_activity.cli:main",]},
     install_requires=install_packages,
-    extras_require={"testing": ["pytest", "pytest-regressions"], "sphinx": ["sphinx", "myst_parser", "sphinx_book_theme"]},
+    extras_require={
+        "testing": ["pytest", "pytest-regressions"],
+        "sphinx": ["sphinx", "myst_parser", "sphinx_book_theme"],
+    },
 )

tests/test_cli.py

@@ -22,14 +22,16 @@ def test_cli(tmpdir, file_regression):
     file_regression.check(md, extension=".md")
 
 
-def test_tags(tmpdir, file_regression):
+def test_pr_split(tmpdir, file_regression):
+    """Test that PRs are properly split by tags/prefixes."""
     path_tmp = Path(tmpdir)
     path_output = path_tmp.joinpath("out.md")
 
-    url = "https://github.com/executablebooks/sphinx-book-theme"
+    url = "https://github.com/executablebooks/jupyter-book"
 
-    # CLI with URL
-    cmd = f"github-activity {url} -s v0.0.2 -u v0.0.4 -o {path_output}"
+    # This release range covers some PRs with tags, and some with prefixes
+    cmd = f"github-activity {url} -s v0.7.1 -u v0.7.3 -o {path_output}"
     out = run(cmd.split(), check=True)
     md = path_output.read_text()
+    md = md.split("## Contributors to this release")[0]
     file_regression.check(md, extension=".md")

tests/test_cli/test_pr_split.md

@@ -0,0 +1,32 @@
+# v0.7.1...v0.7.3
+([full changelog](https://github.com/executablebooks/jupyter-book/compare/v0.7.1...v0.7.3))
+
+
+## New features added
+* ✨ NEW: Adding - chapter entries to _toc.yml [#817](https://github.com/executablebooks/jupyter-book/pull/817) ([@choldgraf](https://github.com/choldgraf))
+
+## Enhancements made
+* 👌 IMPROVE: improving numbered sections [#826](https://github.com/executablebooks/jupyter-book/pull/826) ([@choldgraf](https://github.com/choldgraf))
+* ✨ NEW: Adding - chapter entries to _toc.yml [#817](https://github.com/executablebooks/jupyter-book/pull/817) ([@choldgraf](https://github.com/choldgraf))
+* checking for toc modification time [#772](https://github.com/executablebooks/jupyter-book/pull/772) ([@choldgraf](https://github.com/choldgraf))
+* first pass toc directive [#757](https://github.com/executablebooks/jupyter-book/pull/757) ([@choldgraf](https://github.com/choldgraf))
+
+## Bugs fixed
+* Fix typo in content-blocks.md documentation [#811](https://github.com/executablebooks/jupyter-book/pull/811) ([@MaxGhenis](https://github.com/MaxGhenis))
+* [BUG] Using relative instead of absolute links [#747](https://github.com/executablebooks/jupyter-book/pull/747) ([@AakashGfude](https://github.com/AakashGfude))
+* 🐛 FIX: fixing jupytext install/UI links [#737](https://github.com/executablebooks/jupyter-book/pull/737) ([@chrisjsewell](https://github.com/chrisjsewell))
+
+## Documentation improvements
+* 📚 DOC: update gh-pages + ghp-import docs [#814](https://github.com/executablebooks/jupyter-book/pull/814) ([@TomasBeuzen](https://github.com/TomasBeuzen))
+* 📚 DOC: note about licenses [#806](https://github.com/executablebooks/jupyter-book/pull/806) ([@choldgraf](https://github.com/choldgraf))
+* 📖 DOCS: Fix google analytics instructions [#799](https://github.com/executablebooks/jupyter-book/pull/799) ([@tobydriscoll](https://github.com/tobydriscoll))
+* Change book_path to path_to_book [#773](https://github.com/executablebooks/jupyter-book/pull/773) ([@MaxGhenis](https://github.com/MaxGhenis))
+* GitHub actions example: note about selective build [#771](https://github.com/executablebooks/jupyter-book/pull/771) ([@consideRatio](https://github.com/consideRatio))
+* getting sphinx thebelab to work [#749](https://github.com/executablebooks/jupyter-book/pull/749) ([@choldgraf](https://github.com/choldgraf))
+* Link documentation for adding cell tags in Jupyter from "Hide or remove content" documentation section [#734](https://github.com/executablebooks/jupyter-book/pull/734) ([@MaxGhenis](https://github.com/MaxGhenis))
+* typo fix [#731](https://github.com/executablebooks/jupyter-book/pull/731) ([@MaxGhenis](https://github.com/MaxGhenis))
+
+## API and Breaking Changes
+* ✨ NEW: Adding - chapter entries to _toc.yml [#817](https://github.com/executablebooks/jupyter-book/pull/817) ([@choldgraf](https://github.com/choldgraf))
+* removing config file numbered sections to use toc file instead [#768](https://github.com/executablebooks/jupyter-book/pull/768) ([@choldgraf](https://github.com/choldgraf))
+