Merge pull request #4278 from jgonggrijp/issue-templates

.github/ISSUE_TEMPLATE/Bugs.yml

@@ -0,0 +1,173 @@
+name: Bug report
+description: |
+  Report something that is not working correctly.
+  Not intended for security issues!
+title: Foo.bar should bazoonite, but frobulates instead
+body:
+  - type: markdown
+    attributes:
+      value: "
+        Thank you for taking the effort to report a bug.\n\n
+
+        Is your bug a security issue? In that case, **please do not use this
+        form!** Instead, see the [security
+        policy](https://github.com/jashkenas/backbone/security/policy) on how to
+        report the issue.\n\n
+
+        ## Identification\n\n
+
+        To start, some quick questions to pinpoint the issue."
+  - type: input
+    id: component
+    attributes:
+      label: Affected component
+      description: >
+        Which part of Backbone is affected? Please be as specific as possible,
+        for example “the silent option of Collection.reset” or
+        “importing Backbone with require.js”.
+      placeholder: the sync event triggered after Model.fetch
+    validations:
+      required: true
+  - type: input
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: |
+        In one sentence, what *should* the affected component do?
+      placeholder: |
+        Forward all options passed to Model.fetch to the event handler
+    validations:
+      required: true
+  - type: input
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: |
+        In one sentence, what does the affected component *actually* do?
+      placeholder: |
+        Forward options to the method called last, e.g. save.
+    validations:
+      required: true
+  - type: markdown
+    attributes:
+      value: "
+        After filling the above three fields, please review the issue title. It
+        should be short, including elements of all three fields and not much
+        else.\n\n
+
+        For example: **After Model.fetch, sync event may include
+        options of a later sync, save or destroy call**\n\n
+
+        ## Context"
+  - type: textarea
+    id: docs
+    attributes:
+      label: Relevant documentation
+      description: |
+        Which documentation, if any, did you base your above expectation on?
+        Provide one link per line.
+      placeholder: |
+        - https://backbonejs.org/#Model-fetch
+        - https://backbonejs.org/#Events-catalog
+  - type: textarea
+    id: stack
+    attributes:
+      label: Software stack
+      description: "
+        With which version(s) of Backbone, Underscore/Lodash, jQuery/Zepto,
+        other relevant libraries or tools, your browser, etcetera, did you
+        experience this problem? Please list one per line, including name,
+        version number(s) and variant(s) if applicable.\n\n
+
+        **Tip:** if you are using the bleeding-edge version of
+        Backbone, much of this information can be obtained by using
+        [debugInfo](https://backbonejs.org/#Utility-Backbone-debugInfo)
+        and copy-pasting its console output below."
+      placeholder: "
+        - Backbone 1.4.1 and latest `master` (commit fcf5df6)\n
+        - Underscore 1.13.6\n
+        - jQuery 3.6.3 (slim build)\n
+        - Marionette 4.1.2\n
+        - Firefox 100\n
+        - Node.js 14.6\n
+
+        OR (stretch form field to see example content):\n
+
+        ```json\n
+        Backbone debug info:  {\n
+        \ \ \"backbone\": \"1.5.0\",\n
+        \ \ \"distribution\": \"MARK_DEVELOPMENT\",\n
+        \ \ \"_\": \"lodash 4.17.21\",\n
+        \ \ \"$\": \"3.6.0\",\n
+        \ \ \"navigator\": {\n
+        \ \ \ \ \"userAgent\": \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:109.0) Gecko/20100101 Firefox/116.0\",\n
+        \ \ \ \ \"platform\": \"MacIntel\",\n
+        \ \ \ \ \"webdriver\": false\n
+        \ \ }\n
+        }\n
+        ```\n
+
+        - Backbone `master` checked out on August 10, 2023\n
+        - Marionette 4.1.2"
+    validations:
+      required: true
+  - type: textarea
+    id: discourse
+    attributes:
+      label: Related issues, prior discussion and CCs
+      description: >
+        Please list any issue numbers, pull requests or links to discussions
+        elsewhere on the internet that may be relevant. You can also attract the
+        attention of other GitHub users by listing their `@handles` here.
+      placeholder: "
+        #4229, #3410\n
+        a Stack Overflow or Matrix link\n
+        @jgonggrijp"
+  - type: markdown
+    attributes:
+      value: "## Bug details"
+  - type: input
+    id: error
+    attributes:
+      label: Error
+      description: >
+        If possible, name the error that you observed and that anyone trying to
+        reproduce the bug should look for.
+      placeholder: TypeError (options.success is not an object)
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: >
+        List the minimal steps needed to make the bug happen. Include code
+        examples as needed.
+    validations:
+      required: true
+  - type: textarea
+    id: details
+    attributes:
+      label: Additional information
+      description: >-
+        This is a free-form field where you can add any further details that may
+        help to understand the bug. For example, you might provide permalinks to
+        the affected lines of code in your actual project, attach logs or
+        screenshots, point out things you noticed while debugging, and explain
+        why the bug is especially problematic for your use case.
+  - type: markdown
+    attributes:
+      value: "## Closing"
+  - type: textarea
+    id: solution
+    attributes:
+      label: Suggested solution(s)
+      description: >
+        If you have any idea on how the problem could (or should) be solved,
+        please feel welcome to describe it here. Of course, if your idea is very
+        concrete, you may as well submit a pull request!
+  - type: textarea
+    id: remarks
+    attributes:
+      label: Other remarks
+      description: >-
+        If there is anything else you would like to say about the issue, you can
+        do so here.

.github/ISSUE_TEMPLATE/Documentation.yml

@@ -0,0 +1,76 @@
+name: Documentation issue
+description: >-
+  Report information that is missing, incomplete, vague, misleading or plain
+  wrong in online documentation such as the website, the README, the wiki,
+  etcetera.
+body:
+  - type: markdown
+    attributes:
+      value: >-
+        Thank you for taking the time to help us improve the documentation.
+  - type: input
+    id: reference
+    attributes:
+      label: Reference to current documentation
+      description: >-
+        If you can identify an existing piece of documentation that is lacking,
+        please provide a URL (or multiple) below. If your report is about
+        missing information and there is no single obvious place where it should
+        be added, you can leave this empty.
+      placeholder: "https://backbonejs.org/#Model-changedAttributes"
+  - type: textarea
+    id: quote
+    attributes:
+      label: Quote of current documentation
+      description: >-
+        If you provided a URL in the previous field, please quote the
+        problematic documentation below. This ensures that future readers
+        understand what you were responding to, in case the referred page
+        disappears or changes content.
+      placeholder: "
+        > Retrieve a hash of only the model's attributes that have changed since
+        the last
+        [set](https://backbonejs.org/#Model-set), or `false` if there are none.
+        Optionally, an external **attributes** hash can be passed in, returning
+        the attributes in that hash which differ from the model. This can be
+        used to figure out which portions of a view should be updated, or what
+        calls need to be made to sync the changes to the server."
+  - type: textarea
+    id: effect
+    attributes:
+      label: Effect of the problem
+      description: >-
+        What did you or someone else not know, misunderstand or falsely believe
+        due to the current state of the documentation? How has this misguided
+        your or someone else's behavior?
+      placeholder: >-
+        I did not know that I could ..., so I needlessly ...
+    validations:
+      required: true
+  - type: textarea
+    id: cause
+    attributes:
+      label: Cause of the problem
+      description: >-
+        What is it about the current documentation that caused your problem?
+        What is missing, ambiguous or wrong? Pinpoint specific words or phrases
+        if possible.
+      placeholder: >-
+        It says "...", which seems to suggest that ..., while actually, ...
+    validations:
+      required: true
+  - type: textarea
+    id: suggestion
+    attributes:
+      label: Suggestion
+      description: >-
+        If you have any idea on how the documentation could be improved, please
+        share it here. Of course, if your idea is very concrete, you can also
+        submit a pull request!
+  - type: textarea
+    id: remarks
+    attributes:
+      label: Other remarks
+      description: >-
+        If there is anything else you would like to say about the issue, you can
+        do so here.

.github/ISSUE_TEMPLATE/Features.yml

@@ -0,0 +1,72 @@
+name: Feature request
+description: >-
+  Tell us about functionality that you miss in Backbone.
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for proposing a new feature.
+
+        Let us begin with the end in mind.
+  - type: textarea
+    id: goal
+    attributes:
+      label: Ultimate goal
+      description: >-
+        This first question is not about Backbone but about the mission that you
+        hope to accomplish with Backbone. What work do you need to get done?
+      placeholder: |
+        GOOD: I work on an application that needs to ...
+        BAD (later question): I think Backbone.Collection should have a method that ...
+    validations:
+      required: true
+  - type: textarea
+    id: shortcoming
+    attributes:
+      label: Shortcomings
+      description: >-
+        Working towards your end goal, what task is currently difficult to
+        achieve with Backbone as it is? Which features in Backbone or other
+        libraries are currently available to you, which do not quite do what you
+        need?
+      placeholder: |
+        In my application, I need to ..., but when I define a
+        Backbone.Collection subclass, there does not seem to be any way to ...
+
+        - I could use `Collection.slice`, but ...
+        - I could use <some other library>, but ...
+    validations:
+      required: true
+  - type: textarea
+    id: justification
+    attributes:
+      label: Justification
+      description: >-
+        Why do you believe that the missing functionality belongs in Backbone
+        proper? Why could or should it not be provided by another library or
+        tool?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposal
+      description: >-
+        Go ahead, describe your ideal solution. Show what it should look like
+        and explain how it should behave.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Possible alternatives
+      description: >-
+        Can you think of other ways in which your desired functionality could be
+        provided? If they appeal less to you, why is this the case?
+  - type: textarea
+    id: remarks
+    attributes:
+      label: Other remarks
+      description: >-
+        If there is anything else you would like to say about your feature
+        request, you can do so here.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,10 @@
+contact_links:
+  - name: Security issue
+    url: https://github.com/jashkenas/backbone/security/policy
+    about: Go here if you would like to report a security issue.
+  - name: Stack Overflow
+    url: https://stackoverflow.com/questions/tagged/backbone.js
+    about: The best place to get help making your code work (be sure to include the `backbone.js` tag).
+  - name: Matrix/Gitter
+    url: https://matrix.to/#/#jashkenas_backbone:gitter.im
+    about: Discussions about, and general help with, Backbone.

backbone.js

@@ -2144,5 +2144,12 @@
     };
   };
 
+  // Provide useful information when things go wrong. This method is not meant
+  // to be used directly; it merely provides the necessary introspection for the
+  // external `debugInfo` function.
+  Backbone._debug = function() {
+    return {root: root, _: _};
+  };
+
   return Backbone;
 });

debug-info.js

@@ -0,0 +1,38 @@
+(function (global, factory) {
+  typeof exports === 'object' && typeof module !== 'undefined' ? module.exports = factory(require('backbone')) :
+  typeof define === 'function' && define.amd ? define(['backbone'], factory) :
+  (global = typeof globalThis !== 'undefined' ? globalThis : global || self, (global.Backbone = global.Backbone || {}, global.Backbone.debugInfo = factory(global.Backbone)));
+})(this, (function (Backbone) {
+  // Provide useful information when things go wrong.
+  function debugInfo() {
+    // Introspect Backbone.
+    var $ = Backbone.$, _b = Backbone._debug(), _ = _b._, root = _b.root;
+    // Use the `partialRight` function as a Lodash indicator. It was never in
+    // Underscore, has been in Lodash at least since version 1.3.1, and is
+    // unlikely to be mixed into Underscore since nobody needs it.
+    var lodash = !!_.partialRight;
+    var info = {
+      backbone: Backbone.VERSION,
+      // Is this the exact released version, or a later development version?
+      /* This is automatically temporarily replaced when publishing a release,
+         so please don't edit this. */
+      distribution: 'MARK_DEVELOPMENT',
+      _: (lodash ? 'lodash ' : '') + _.VERSION,
+      $: !$ ? false : $.fn && $.fn.jquery ? $.fn.jquery :
+        $.zepto ? 'zepto' : $.ender ? 'ender' : true
+    };
+    if (typeof root.Deno !== 'undefined') {
+      info.deno = _.pick(root.Deno, 'version', 'build');
+    } else if (typeof root.process !== 'undefined') {
+      info.process = _.pick(root.process, 'version', 'platform', 'arch');
+    } else if (typeof root.navigator !== 'undefined') {
+      info.navigator = _.pick(root.navigator, 'userAgent', 'platform', 'webdriver');
+    }
+    /* eslint-disable-next-line no-console */
+    console.debug('Backbone debug info: ', JSON.stringify(info, null, 4));
+    return info;
+  }
+
+  return debugInfo;
+
+}));