Add issue templates for Github

.dir-locals.el

@@ -3,4 +3,6 @@
 
 ((emacs-lisp-mode . ((sentence-end-double-space . t)
                      (indent-tabs-mode . nil)))
- (makefile-mode . ((indent-tabs-mode . t))))
+ (makefile-mode . ((indent-tabs-mode . t)))
+ (org-mode . ((sentence-end-double-space . nil)
+              (fill-column . 70))))

.github/ISSUE_TEMPLATE/BUG-REPORT.yml

@@ -0,0 +1,61 @@
+name: Bug Report
+description: File a bug report
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report!
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: Expected behavior
+      description: How do you expect the
+      value: "Something should happen"
+    validations:
+      required: true
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: Actual behavior
+      description: How is what happened different from the expected behavior?
+      value: "Something else happened"
+    validations:
+      required: true
+  - type: dropdown
+    id: package-version
+    attributes:
+      label: org-unique-id version
+      description: What version of org-unique-id are you using?
+      options:
+        - master
+        - 0.4.1
+        - 0.4.0
+        - 0.3.1
+        - 0.3.0
+        - something else (please specify)
+  - type: dropdown
+    id: emacs-version
+    attributes:
+      label: Emacs version
+      description: Which version of Emacs are you using?
+      options:
+        - 28.1
+        - 27.2
+        - 27.1
+        - 26.3
+        - 26.2
+        - 26.1
+        - 25.3
+        - 25.2
+        - 25.1
+        - master
+        - something else (please specify)
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant code or log output
+      description: Please copy and pase any relevant code or log output. This will be automatically formatted into code, so no need for backticks
+      render: emacs-lisp

.github/ISSUE_TEMPLATE/FEATURE-REQUEST.yml

@@ -0,0 +1,33 @@
+name: Feature Request
+description: Request a new feature
+title: "[Feature Request]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to request a new feature!
+  - type: textarea
+    id: feature-description
+    attributes:
+      label: New feature
+      description: Description of the new feature
+      value: "New function org-unique-id-thing should do thing"
+    validations:
+      required: true
+  - type: textarea
+    id: feature-reason
+    attributes:
+      label: Why this new feature
+      description: Describe why this new feature should be added to org-unique-id
+      value: "New function org-unique-id-thing does something often done by people"
+    validations:
+      required: true
+  - type: textarea
+    id: ideas-implementation
+    attributes:
+      label: Implementation ideas and additional thoughts
+      description: Do you have an idea on how to implement it?
+      value: "It could be implemented doing foo, bar, and baz"
+    validations:
+      required: false

CONTRIBUTING.org

@@ -11,6 +11,7 @@ hard to follow them.
 - [[#how-can-i-contribute][How Can I Contribute?]]
   - [[#submitting-bugs-and-errors][Submitting Bugs and Errors]]
   - [[#submitting-new-code][Submitting New Code]]
+    - [[#ensuring-the-quality-of-your-code][Ensuring the quality of your code]]
     - [[#git-commit-messages][Git Commit Messages]]
     - [[#describing-the-pull-request][Describing the Pull Request]]
   - [[#finding-something-to-do][Finding Something To Do]]
@@ -31,7 +32,7 @@ information as possible:
 As you are collecting these pieces of information, try to come up with
 a short and clear issue title –it should describe quickly your issue
 without being too vague (e.g. avoid stuff like “error when opening
-Eshell” or “doesn’t work”).
+org-mode” or “doesn’t work”).
 
 ** Submitting New Code
 If you are submitting new code through a pull request, make sure of
@@ -46,6 +47,15 @@ the following:
 - And obviously, your code works (I include that because I myself
   sometimes push commits that don’t work)
 
+*** Ensuring the quality of your code
+Although a CI is already in place on the Github repository, you are
+encouraged to make sure yourself everything runs correctly.
+
+This package uses [[https://github.com/emacs-eask/eask][Eask]] to run its linters. Once it is installed, you
+can go to your preferred terminal and run ~make ci~. If everything goes
+well, you’re ready to submit your code to the repository. If not,
+please fix whatever Eask complains about first.
+
 *** Git Commit Messages
 Your commits should also follow [[https://github.com/syl20bnr/spacemacs/blob/develop/CONTRIBUTING.org#commit-messages][Spacemacs’ guidelines]] on this matter,
 especially:
@@ -65,10 +75,10 @@ clear as to what it is meant to do. Its description should:
 ** Finding Something To Do
 Not sure where to begin? Take a look at the list of open issues,
 especially the ones with one of the following labels:
-- [[https://github.com/Phundrak/eshell-info-banner.el/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22good+first+issue%22][/good first issue/]] :: These issues indicate easy to fix issues and
+- [[https://github.com/Phundrak/org-unique-id/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22good+first+issue%22][/good first issue/]] :: These issues indicate easy to fix issues and
   easy to implement enhancements. If you are a beginner or if you want
   to familiarize yourself with the package, look for these issues.
-- [[https://github.com/Phundrak/eshell-info-banner.el/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22+sort%3Aupdated-desc][/help wanted/]] :: These issues might require some more work than /good
+- [[https://github.com/Phundrak/org-unique-id/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22+sort%3Aupdated-desc][/help wanted/]] :: These issues might require some more work than /good
   first issue/ issues and might be a bit more interesting.
 If you want to work on an open issue, leave a comment saying
 so. However, you can directly submit a pull request if you are simply

Eask

@@ -1,5 +1,5 @@
 (package "org-unique-id"
-         "0.3.0"
+         "0.3.1"
          "Create unique IDs for org headers")
 
 (website-url "https://labs.phundrak.com/phundrak/org-unique-id")

README.org

@@ -2,6 +2,8 @@
 #+author: Lucien Cartier-Tilet
 #+email: lucien@phundrak.com
 [[https://github.com/Phundrak/org-unique-id/actions/workflows/workflow.yml][file:https://github.com/Phundrak/org-unique-id/actions/workflows/workflow.yml/badge.svg]]
+[[https://melpa.org/#/org-unique-id][file:https://melpa.org/packages/org-unique-id-badge.svg]]
+[[https://stable.melpa.org/#/org-unique-id][file:https://stable.melpa.org/packages/org-unique-id-badge.svg]]
 
 * Introduction
 ~org-unique-id~ is a utility package for org users that are tired
@@ -14,6 +16,8 @@ user modifies them manually.
 - [[#introduction][Introduction]]
 - [[#installation][Installation]]
 - [[#usage][Usage]]
+- [[#breaking-changes][Breaking changes]]
+  - [[#040][~0.4.0~]]
 - [[#contributing][Contributing]]
 - [[#license][License]]
 
@@ -49,12 +53,12 @@ While ~org-unique-id~ may be installed on your Emacs instance, it is not
 active by default. This is because it can take some time to generate
 all the required IDs in your org file which may hang your Emacs
 instance for a bit. Therefore, automatic IDs are enabled on a per-file
-basis with the option ~auto-id~.
+basis with the option ~unique-id~.
 
 Here is an example of an org buffer with ~org-unique-id~ enabled:
 #+begin_src org
 ,#+title: Test file
-,#+options: auto-id:t
+,#+options: unique-id:t
 
 ,* Test level 1
 :PROPERTIES:
@@ -77,7 +81,7 @@ the ~CUSTOM_ID~ and let ~org-unique-id~ regenerate it. If you don’t like
 the ~CUSTOM_ID~ generated by ~org-unique-id~, you can overwrite it
 yourself and ~org-unique-id~ will not modify it.
 
-Note that ~auto-id:t~ is absolutely required in order to get these
+Note that ~unique-id:t~ is absolutely required in order to get these
 ~CUSTOM_ID~. Here is the same buffer after save without this option:
 #+begin_src org
 ,#+title: Test file
@@ -88,7 +92,11 @@ Note that ~auto-id:t~ is absolutely required in order to get these
 
 It is also possible to manually call ~org-unique-id~ (interactively or
 not) on the current buffer. This will not check the value of the
-~auto-id~ option.
+~unique-id~ option.
+
+* Breaking changes
+** ~0.4.0~
+The option ~auto-id~ is renamed to ~unique-id~.
 
 * Contributing
 See [[file:CONTRIBUTING.org]].

org-unique-id.el

@@ -2,7 +2,7 @@
 
 ;; Author: Lucien Cartier-Tilet <lucien@phundrak.com>
 ;; Maintainer: Lucien Cartier-Tilet <lucien@phundrak.com>
-;; Version: 0.3.1
+;; Version: 0.4.1
 ;; Package-Requires: ((emacs "25.1") (org "9.3"))
 ;; Homepage: https://labs.phundrak.com/phundrak/org-unique-id
 ;; Keywords: convenience
@@ -26,17 +26,52 @@
 
 ;;; Commentary:
 
-;; This package is inspired by a blog post I published about a year
-;; before I decided to write this package [1], which in turn is
-;; largely inspired by another blog post [2].
+;; org-unique-id is a utility package for org-mode users that are
+;; tired dealing with random org IDs for their headers’ anchor that
+;; change on each org to HTML exports among others.  This package
+;; creates meaningful custom IDs for org headers that won’t change
+;; unless the user modifies or removes them manually.
 ;;
-;; It will generate a unique ID for each headers in an org file based
-;; on the headers’ name plus a random short string in order to be sure
-;; to make it unique.  This ID will be inserted in each header’s
-;; properties as a custom ID.
+;; In order to be enabled, this package’s `org-unique-id-maybe'
+;; function must be hooked to `before-save-hook', and the string
+;; \\='unique-id:t\\=' must be present in an \\='#+OPTIONS:\\=' line
+;; in the buffer.
 ;;
-;; [1] https://blog.phundrak.com/better-custom-ids-orgmode/
-;; [2] https://writequit.org/articles/emacs-org-mode-generate-ids.html
+;; If the \\='unique-id:t\\=' string is found, then it will create a
+;; slug of the current header (and if there are, its parent headers)
+;; and it will add a unique string suffix generated with a UUID
+;; generator to ensure all IDs are unique.
+;;
+;; Here is an example of an org-mode file without the
+;; \\='unique-id:t\\=' option after save:
+;;
+;;     #+title: Test file
+;;     * Test level 1
+;;     ** Test level 2
+;;     * Test level 1
+;;
+;; And here is the same org-mode file but with the option atop its
+;; content:
+;;
+;;     ,#+title: Test file
+;;     ,#+options: unique-id:t
+;;     ,* Test level 1
+;;     :PROPERTIES:
+;;     :CUSTOM_ID: Test-level-1-zmb40t305kj0
+;;     :END:
+;;     ,** Test level 2
+;;     :PROPERTIES:
+;;     :CUSTOM_ID: Test-level-1-Test-level-2-spn40t305kj0
+;;     :END:
+;;     ,* Test level 1
+;;     :PROPERTIES:
+;;     :CUSTOM_ID: Test-level-1-1nx40t305kj0
+;;     :END:
+;;
+;; Of course the last part of the custom ID might differ for you, but
+;; once it is generated, org-unique-id will not modify it or
+;; regenerate it unless you delete it yourself, hence ensuring a
+;; constant ID for your org exports.
 
 ;;; Code:
 
@@ -112,8 +147,8 @@ case, the CUSTOM_ID of the entry is returned."
 (defun org-unique-id ()
   "Add a CUSTOM_ID to all headers missing one.
 
-Only adds ids if the `auto-id' option is set to t in the file
-somewhere, i.e. #+OPTIONS: auto-id:t"
+Only adds ids if the \\='unique-id\\=' option is set to t in the
+file somewhere, i.e. #+OPTIONS: unique-id:t"
   (interactive)
   (save-excursion
     (widen)
@@ -126,14 +161,14 @@ somewhere, i.e. #+OPTIONS: auto-id:t"
 
 This function executes `org-unique-id' when the buffer’s major
 mode is `org-mode', when the buffer is not read-only, and if
-\\='auto-id:t\\' is found in an #+OPTIONS line."
+\\='unique-id:t\\' is found in an #+OPTIONS line."
   (interactive)
   (when (and (eq major-mode 'org-mode)
-             (eq buffer-read-only nil)
+             (not buffer-read-only)
              (save-excursion
                (goto-char (point-min))
                (let ((case-fold-search t))
-                 (re-search-forward "^#\\+OPTIONS:.*auto-id:t" (point-max) t))))
+                 (re-search-forward "^#\\+OPTIONS:.*unique-id:t" (point-max) t))))
     (org-unique-id)))
 
 (provide 'org-unique-id)