Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve scriv create fragment template #68

Closed
ncoghlan opened this issue Nov 5, 2024 · 2 comments
Closed

Improve scriv create fragment template #68

ncoghlan opened this issue Nov 5, 2024 · 2 comments

Comments

@ncoghlan
Copy link
Collaborator

ncoghlan commented Nov 5, 2024

The default scriv fragment is quite noisy, and doesn't establish conventions for particular fragments.

Default templates (as modified by the open scriv PR at nedbat/scriv#134).

Markdown:

<!--
A new scriv changelog fragment.

Uncomment the section that is right (remove the HTML comment wrapper).
For top level release notes, leave all the headers commented out.
-->

{% for cat in config.categories -%}
<!--
### {{ cat }}

- A bullet item for the {{ cat }} category.

-->
{% endfor -%}

ReST:

.. A new scriv changelog fragment.
{% if config.categories -%}
..
.. Uncomment the section that is right (remove the leading dots).
.. For top level release notes, leave all the headers commented out.
..
{% for cat in config.categories -%}
.. {{ cat }}
.. {{ config.rst_header_chars[1] * (cat|length) }}
..
.. - A bullet item for the {{ cat }} category.
..
{% endfor -%}
{% else %}
- A bullet item for this fragment. EDIT ME!
{% endif -%}
@ncoghlan
Copy link
Collaborator Author

ncoghlan commented Nov 5, 2024

Initial thoughts for an update is to just include one representative example, and edit
the category heading in place, instead of having lots of duplicated entries to be deleted.

Markdown:

<!--
Defined changelog categories:
{% for cat in config.categories -%}
  - {{ cat }}
{% endfor -%}

Replace "Category" below with the relevant category name.
For top level release notes, delete the category header entirely.
Use the ReST format for notes that need to refer to issue numbers.

Deleting this header after editing is recommended.
-->

### Category

- Release note details.

ReST:

.. Defined changelog categories:
{% for cat in config.categories -%}
..   - {{ cat }}
{% endfor -%}
..
.. Replace "Category" below with the relevant category name.
.. Adjust the heading underline to match the chosen category name.
.. For top level release notes, delete the category header entirely.
.. Update the referenced issue number as appropriate.
.. "resolved" works for most categories, but replace the verb as necessary.
.. Use `:pr:`NN` to refer to pull requests. Other Sphinx roles also work here.
..
.. Deleting this header after editing is recommended.

Category
--------

- Release note details (resolved in :issue:`NN`).

@ncoghlan
Copy link
Collaborator Author

ncoghlan commented Nov 8, 2024

Defining a markdown fragment template isn't necessary, as I misunderstood the granularity of scriv's format option (you can't mix and match fragment formats - any given project must exclusively use either ReST fragments or Markdown fragments).

(I want to use ReST so the :issue:`NN` and :pr:`NN` semantic references work).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant