Contrib.social

Add "Introduced terminology" section to the "Bare issue summary template" default heading for new issues

Open on Drupal.org →
Created on 24 May 2024, 7 months ago
Updated 6 August 2024, 5 months ago

Problem/Motivation

Proposing adding a "Introduced terminology" section in the default new issue template for Drupal core. The heading is for core contributors to list new words or terms they are adding to Drupal core or identify new ways they are using an existing word in their work.

The Drupalisms working group is cataloging existing words in the Drupal core code base, including words that also appear in the administration user interface, in order to identify Drupalisms which are "Drupal terms that cause confusion". More information about this work is available in De-jargoning Drupal – working with the community to open up Drupal’s terminology → .

New code is added to Drupal core regularly. By encouraging core contributors to identify what words or terms they are introducing in the issue summary, it will be more straightforward for the working group to collaborate with core committers to identify words or uses of words that need to be added to the working group's catalog of terminology on an ongoing basis. Surfacing new words may have the added benefit of being more intentional with meaning in the Drupal project as time goes on.

Steps to reproduce

n/a

Proposed resolution

<h3 id="summary-problem-motivation">Problem/Motivation</h3>


<h4 id="summary-steps-reproduce">Steps to reproduce</h4>


<h3 id="summary-proposed-resolution">Proposed resolution</h3>


<h3 id="summary-remaining-tasks">Remaining tasks</h3>


<h3 id="summary-ui-changes">User interface changes</h3>


<h3 id="summary-introduced-terminology">Introduced terminology</h3>


<h3 id="summary-api-changes">API changes</h3>


<h3 id="summary-data-model-changes">Data model changes</h3>


<h3 id="summary-release-notes">Release notes snippet</h3>

Remaining tasks

  1. Add
    <h3 id="summary-introduced-terminology">Introduced terminology</h3>
(New naming and terminology, or additional or changed meanings of existing names and terminology.)

    to the Issue Summary Template → section following <h3 id="summary-ui-changes">User interface changes</h3>

  2. Add
    <h3>Introduced terminology</h3>

<p>A list of new terminology (names for things and concepts), or additions to or changes to meanings of existing names and terminology that will need to be documented on Drupal.org.</p>

<h4>Example</h4>

<blockquote>Topbar

The topbar is the first container element that appears in the viewport when a user is logged in to a Drupal site. It spans the width of the viewport and contains administrative links.</blockquote>

<h4>Details to include</h4>

<ul>
  <li>The terminology name or label.</li>
  <li>A clear and concise description of what the terminology refers to in the code or interface.</li></ul>

    to the Issue Summary Template examples → section, following https://www.drupal.org/node/3156939/#ui-changes →

User interface changes

n/a

API changes

n/a

Data model changes

n/a

Release notes snippet

n/a

📌 Task
Status

Fixed

Version

11.0 🔥

Component
Documentation  →

Last updated 1 day ago

No maintainer
Created by

🇺🇸United States dead_arm

Live updates comments and jobs are added and updated live.
  • Usability

    Makes Drupal easier to use. Preferred over UX, D7UX, etc.

  • Documentation

    Primarily changes documentation, not code. For Drupal core issues, select the Documentation component instead of using this tag. In general, component selection is preferred over tag selection.

Sign in to follow issues

Comments & Activities

  • Issue created by @dead_arm
  • Comment 7 months ago →
    🇺🇸United States dead_arm
  • Status changed to RTBC 7 months ago
  • Comment 7 months ago →
    🇦🇺Australia larowlan 🇦🇺🏝.au GMT+10

    This is a great idea. Thanks

  • Status changed to Needs work 7 months ago
  • Comment 7 months ago →
    🇳🇿New Zealand quietone

    To complete this documentation for this new heading needs to be added to Issue summary field → . I think we should also agree on that as well before making this change to the template. So, can a draft of the changes for that page be added here. Setting to needs work for that.

  • Status changed to Needs review 6 months ago
  • Comment 6 months ago →
    🇺🇸United States dead_arm
  • Comment 6 months ago →
    🇺🇸United States dead_arm

    Thank you! I've added proposed text to include in Issue summary field → to the Remaining tasks.

  • Status changed to RTBC 6 months ago
  • Comment 6 months ago →
    🇺🇸United States smustgrave

    Believe feedback has been addressed/added to issue summary

  • Status changed to Fixed 5 months ago
  • Comment 5 months ago →
    🇬🇧United Kingdom longwave UK

    Added to the default issue template and updated the documentation as per the examples in the IS. I also added an ID to the new h3 in the documentation so it can be linked if required.

  • Status changed to RTBC 5 months ago
  • Comment 5 months ago →
    🇺🇸United States dead_arm
  • Status changed to Fixed 5 months ago
  • Comment 5 months ago →
    🇺🇸United States dead_arm
  • Comment 5 months ago →
    🇬🇧United Kingdom alexpott 🇪🇺🌍

    Do we need to update https://www.drupal.org/docs/develop/issues/fields-and-other-parts-of-an-... → to?

    One thing that makes me hesitate on this change though is that we need a plan for how this information is going to be used. If it's just just going to sit in the issue summary then not many people are going to see it and the value in writing it is minimal. I realise the issue summary says that this will help the initiative and that's a good thing, but I think the process needs to be a bit more apparent. For example, as this is a new section I think the issue summary template could link to initiative and be more explicit about what is expected - other people are not going to know what to do and whether it is relevant. On a large number of issues, i.e. nearly all bug fixes, this section should be removed or N/a'd.

  • Comment 5 months ago →
    🇬🇧United Kingdom longwave UK

    I updated the link in #11. I think this will get slightly more use than "Data model changes" which I can't remember the last time I saw filled in.

    I also find it somewhat funny that we are known as a CMS for structured content and yet here we are, writing structured content into a free text body field, when we raise issues against our own software - if we used proper fields we could have help text, show different fields for bugs vs tasks, etc.

  • Comment 5 months ago →
    System Message

    Automatically closed - issue fixed for 2 weeks with no activity.

contrib.social Blog FAQ Discussions
Production build 0.71.5 2024