wip

Makefile

@@ -5,7 +5,7 @@ cleantests:
 	@rm -rf tests/tmp/.git
 	@rm -rf tests/tmp/empty
 
-generate:
+gen generate:
 	@bash -c 'source tests/helpers.sh && generate ${PWD} tests/tmp'
 
 test: cleantests
@@ -26,17 +26,21 @@ release:
 
 DUTIES = \
 	test-changelog \
+	test-check \
 	test-check-api \
 	test-check-dependencies \
+	test-check-docs \
+	test-check-quality \
+	test-check-types \
 	test-clean \
 	test-coverage \
 	test-docs \
 	test-docs-deploy \
 	test-format \
+	test-help \
+	test-lock \
 	test-release \
-	test-check-quality \
-	test-check-docs \
-	test-check-types \
+	test-setup \
 	test-test
 
 $(DUTIES):

copier.yml

@@ -1,5 +1,5 @@
 # CONFIGURATION -------------------------
-_min_copier_version: "6"
+_min_copier_version: "7"
 _envops:
   autoescape: false
   keep_trailing_newline: true
@@ -116,3 +116,8 @@ python_package_command_line_name:
   type: str
   help: Your CLI name if any (for use in the shell)
   default: "{{ project_name|lower|replace('_', '-')|replace(' ', '-') }}"
+
+insiders:
+  type: bool
+  help: Does this project have an Insiders version?
+  default: false

project/.github/FUNDING.yml.jinja

@@ -1,4 +1,4 @@
-github:
-- {{ author_username }}
+github: {{ author_username }}
+ko_fi: {{ author_username }}
 custom:
 - https://www.paypal.me/{{ author_username }}

project/docs/css/{% if insiders %}insiders.css{% endif %}.jinja

@@ -0,0 +1,63 @@
+@keyframes heart {
+
+  0%,
+  40%,
+  80%,
+  100% {
+    transform: scale(1);
+  }
+
+  20%,
+  60% {
+    transform: scale(1.15);
+  }
+}
+
+.heart {
+  animation: heart 1000ms infinite;
+}
+
+.pulse svg {
+  fill: #00e676 !important;
+}
+
+a.insiders {
+  color: #e91e63;
+}
+
+.sponsorship-list {
+  width: 100%;
+}
+
+.sponsorship-item {
+  float: left;
+  border-radius: 100%;
+  display: block;
+  height: 1.6rem;
+  margin: .2rem;
+  overflow: hidden;
+  width: 1.6rem;
+}
+
+.sponsorship-item:focus, .sponsorship-item:hover {
+  transform: scale(1.1);
+}
+
+.sponsorship-item img {
+  filter: grayscale(100%) opacity(75%);
+  height: auto;
+  width: 100%;
+}
+
+.sponsorship-item:focus img, .sponsorship-item:hover img {
+  filter: grayscale(0);
+}
+
+.sponsorship-item.private {
+  background: var(--md-default-fg-color--lightest);
+  color: var(--md-default-fg-color);
+  font-size: .6rem;
+  font-weight: 700;
+  line-height: 1.6rem;
+  text-align: center;
+}

project/docs/{% if insiders %}insiders.md{% endif %}.jinja

@@ -0,0 +1,189 @@
+# Insiders
+
+{{ project_name }} follows the **sponsorware** release strategy, which means
+that new features are first exclusively released to sponsors as part of
+[Insiders][insiders]. Read on to learn [what sponsorships achieve][sponsorship],
+[how to become a sponsor][sponsors] to get access to Insiders,
+and [what's in it for you][features]!
+
+## What is Insiders?
+
+{{ project_name }} Insiders is a private fork of {{ project_name }}, hosted as
+a private GitHub repository. Almost[^1] [all new features][features]
+are developed as part of this fork, which means that they are immediately
+available to all eligible sponsors, as they are made collaborators of this
+repository.
+
+  [^1]:
+    In general, every new feature is first exclusively released to sponsors, but
+    sometimes upstream dependencies enhance
+    existing features that must be supported by {{ project_name }}.
+
+Every feature is tied to a [funding goal][funding] in monthly subscriptions. When a
+funding goal is hit, the features that are tied to it are merged back into
+{{ project_name }} and released for general availability, making them available
+to all users. Bugfixes are always released in tandem.
+
+Sponsorships start as low as [**$10 a month**][sponsors].[^2]
+
+  [^2]:
+    Note that $10 a month is the minimum amount to become eligible for
+    Insiders. While GitHub Sponsors also allows to sponsor lower amounts or
+    one-time amounts, those can't be granted access to Insiders due to
+    technical reasons. Such contributions are still very much welcome as
+    they help ensuring the project's sustainability.
+
+
+## What sponsorships achieve
+
+Sponsorships make this project sustainable, as they buy the maintainers of this
+project time – a very scarce resource – which is spent on the development of new
+features, bug fixing, stability improvement, issue triage and general support.
+The biggest bottleneck in Open Source is time.[^3]
+
+  [^3]:
+    Making an Open Source project sustainable is exceptionally hard: maintainers
+    burn out, projects are abandoned. That's not great and very unpredictable.
+    The sponsorware model ensures that if you decide to use {{ project_name }},
+    you can be sure that bugs are fixed quickly and new features are added
+    regularly.
+
+If you're unsure if you should sponsor this project, check out the list of
+[completed funding goals][goals completed] to learn whether you're already using features that
+were developed with the help of sponsorships. You're most likely using at least
+a handful of them, [thanks to our awesome sponsors][sponsors]!
+
+## What's in it for me?
+
+```python exec="1" session="insiders"
+data_source = "docs/insiders.yml"
+--8<-- "scripts/insiders.py"
+
+print(f"""The moment you <a href="#how-to-become-a-sponsor">become a sponsor</a>, you'll get **immediate
+access to {len(completed_features)} additional features** that you can start using right away, and
+which are currently exclusively available to sponsors:\n""")
+
+print_features(completed_features)
+```
+
+## How to become a sponsor
+
+Thanks for your interest in sponsoring! In order to become an eligible sponsor
+with your GitHub account, visit [{{ author_username }}'s sponsor profile][github sponsor profile],
+and complete a sponsorship of **$10 a month or more**.
+You can use your individual or organization GitHub account for sponsoring.
+
+**Important**: If you're sponsoring **[@{{ author_username }}][github sponsor profile]**
+through a GitHub organization, please send a short email
+to {{ author_email }} with the name of your
+organization and the GitHub account of the individual
+that should be added as a collaborator.[^4]
+
+You can cancel your sponsorship anytime.[^5]
+
+  [^4]:
+    It's currently not possible to grant access to each member of an
+    organization, as GitHub only allows for adding users. Thus, after
+    sponsoring, please send an email to {{ author_email }}, stating which
+    account should become a collaborator of the Insiders repository. We're
+    working on a solution which will make access to organizations much simpler.
+    To ensure that access is not tied to a particular individual GitHub account,
+    create a bot account (i.e. a GitHub account that is not tied to a specific
+    individual), and use this account for the sponsoring. After being added to
+    the list of collaborators, the bot account can create a private fork of the
+    private Insiders GitHub repository, and grant access to all members of the
+    organizations.
+
+  [^5]:
+    If you cancel your sponsorship, GitHub schedules a cancellation request
+    which will become effective at the end of the billing cycle. This means
+    that even though you cancel your sponsorship, you will keep your access to
+    Insiders as long as your cancellation isn't effective. All charges are
+    processed by GitHub through Stripe. As we don't receive any information
+    regarding your payment, and GitHub doesn't offer refunds, sponsorships are
+    non-refundable.
+
+
+```python exec="1" session="insiders"
+print_join_sponsors_button()
+```
+
+{#
+**Silver sponsors**:
+
+[![FastAPI]{ style="height: 120px" }](https://fastapi.tiangolo.com/){ target=_blank title="FastAPI" }
+
+**Bronze sponsors**:
+
+[![Cirrus CI]](https://cirrus-ci.org/){ target=_blank title="Cirrus CI" }
+
+</div>
+
+  [FastAPI]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-fastapi.png
+
+<hr>
+#}
+
+<div class="sponsorship-list" markdown>
+
+```python exec="1" session="insiders"
+print_sponsors()
+```
+
+</div>
+
+<br>
+
+<small>
+  If you sponsor publicly, you're automatically added here with a link to
+  your profile and avatar to show your support for Material for MkDocs.
+  Alternatively, if you wish to keep your sponsorship private, you'll be a
+  silent +1. You can select visibility during checkout and change it
+  afterwards.
+</small>
+
+## Funding
+
+```python exec="1" session="insiders" idprefix=""
+print(f"Current funding is at **$ {human_readable_amount(current_funding)}  a month**.")
+```
+
+### Goals
+
+The following section lists all funding goals. Each goal contains a list of
+features prefixed with a checkmark symbol, denoting whether a feature is
+:octicons-check-circle-fill-24:{ style="color: #00e676" } already available or 
+:octicons-check-circle-fill-24:{ style="color: var(--md-default-fg-color--lightest)" } planned,
+but not yet implemented. When the funding goal is hit,
+the features are released for general availability.
+
+```python exec="1" session="insiders" idprefix=""
+for goal in goals.values():
+    if not goal.complete:
+        goal.render()
+```
+
+### Goals completed
+
+This section lists all funding goals that were previously completed, which means
+that those features were part of Insiders, but are now generally available and
+can be used by all users.
+
+```python exec="1" session="insiders"
+for goal in goals.values():
+    if goal.complete:
+        goal.render()
+```
+
+## Frequently asked questions
+
+### Compatibility
+
+
+[insiders]: #what-is-insiders
+[sponsorship]: #what-sponsorships-achieve
+[sponsors]: #how-to-become-a-sponsor
+[features]: #whats-in-it-for-me
+[funding]: #funding
+[goals completed]: #goals-completed
+[github sponsor profile]: https://github.com/sponsors/{{ author_username }}

project/docs/{% if insiders %}insiders.yml{% endif %}.jinja

@@ -0,0 +1,25 @@
+goals:
+  500:
+    name: Brutal Black
+    features:
+    - name: Some Feature 1a
+      ref: some-feature-1a
+      since: 2022/01/01
+    - name: Some Feature 1b
+      ref: some-feature-1b
+      since: 2022/02/02
+  1000:
+    name: Happy Hardcore
+    features:
+    - name: Some Feature 2a
+      ref: some-feature-2a
+      since: 2023/03/03
+    - name: Some Feature 2b
+      ref: some-feature-2b
+      since: null
+  2000:
+    name: Breakcore
+    features:
+    - name: Some Feature 3
+      ref: some-feature-3
+      since: null

project/mkdocs.yml.jinja

@@ -18,6 +18,9 @@ nav:
   - Contributing: contributing.md
   - Code of Conduct: code_of_conduct.md
   - Coverage report: coverage.md
+{%- if insiders %}
+- Insiders: insiders.md
+{%- endif %}
 {%- if author_username == "pawamoy" %}
 - Author's website: https://{{ author_username }}.{{ repository_provider.rsplit('.', 1)[0] }}.io/
 {%- endif %}
@@ -53,18 +56,26 @@ theme:
 extra_css:
 - css/material.css
 - css/mkdocstrings.css
+{%- if insiders %}
+- css/insiders.css
+{%- endif %}
 
 markdown_extensions:
+- attr_list
 - admonition
 - callouts
-- pymdownx.emoji
+- footnotes
+- pymdownx.emoji:
+    emoji_index: !!python/name:materialx.emoji.twemoji
+    emoji_generator: !!python/name:materialx.emoji.to_svg
 - pymdownx.magiclink
 - pymdownx.snippets:
     check_paths: true
 - pymdownx.superfences
 - pymdownx.tabbed:
     alternate_style: true
-- pymdownx.tasklist
+- pymdownx.tasklist:
+    custom_checkbox: true
 - toc:
     permalink: {% if author_username == "pawamoy" %}"¤"{% else %}true{% endif %}
 

project/pyproject.toml.jinja

@@ -150,6 +150,7 @@ tests = [
 typing = [
     "mypy>=0.910",
     "types-markdown>=3.3",
+    "types-pyyaml>=6.0",
     "types-toml>=0.10",
 ]
 security = ["safety>=2"]