Road to 1.0.0

.github/FUNDING.yml

@@ -0,0 +1,13 @@
+# These are supported funding model platforms
+
+github: guidoschmidt
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+otechie: # Replace with a single Otechie username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

.github/ISSUE_TEMPLATE/bug-report.md

@@ -0,0 +1,31 @@
+---
+name: Bug report
+about: Create a report to report a bug in circadian.el
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Environment (please complete the following information):**
+ - OS: [e.g. macOS 14, Windows 11, Ubuntu etc.]
+ - Emacs: [e.g. emacs-plus 30.0.50]
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/workflows/ci.yml

@@ -6,24 +6,24 @@ jobs:
     strategy:
       matrix:
         emacs-version:
-          - 26.3
           - 27.2
           - 28.2
+          - 29.3
           - snapshot
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
 
       - uses: purcell/setup-emacs@master
         with:
           version: ${{ matrix.emacs-version }}
 
-      - uses: actions/cache@v2
+      - uses: actions/cache@v4
         id: cache-cask-packages
         with:
           path: .cask
           key: cache-cask-packages-000
 
-      - uses: actions/cache@v2
+      - uses: actions/cache@v4
         id: cache-cask-executable
         with:
           path: ~/.cask

README.md

@@ -16,7 +16,7 @@
   <h3 align="center">Theme-switching for Emacs based on daytime</h3>
 </p>
 
-### Conception
+## Conception
 
 Circadian tries to help reducing eye strain that may arise
 from difference of your display brightness and the
@@ -31,9 +31,63 @@ adaption software like:
 
 ---
 
-### Example usage
+## Usage & Configuration
+Install circadian.el with
+[use-package](https://www.gnu.org/software/emacs/manual/html_mono/use-package.html)
+or [straight.el](https://github.com/radian-software/straight.el)
 
-##### Switching themes on time of day
+### Configuration with times
+To auto-switch a theme on a specific time, use time strings:
+
+```elisp
+(use-package circadian
+  :ensure t
+  :config
+  (setq circadian-themes '(("8:00" . wombat)
+                           ("19:30" . adwaita)))
+  (circadian-setup))
+```
+
+
+### Configuration with `:sunrise` and `:sunset`
+To auto-switch a theme based on your current locations sunrise and sunset times:
+
+1. Make sure to set your latitude and longitude (Get them e.g. at
+   [latlong.net](https://www.latlong.net/)):
+    ```elisp
+      (setq calendar-latitude 40.712776)
+      (setq calendar-longitude -74.005974)
+    ```
+2. Configure `circadian-themes` using the `:sunset` and `:sunset`
+    ```elisp
+    (use-package circadian
+      :ensure t
+      :config
+      (setq circadian-themes '((:sunrise . adwaita)
+                               (:sunset  . wombat)))
+      (circadian-setup))
+    ```
+
+
+### Randomly selection from theme list
+Circadian.el can randomly select a theme from a given list, e.g here using [doom-themes](https://github.com/doomemacs/themes) at sunset:
+
+```elisp
+(use-package doom-themes)
+
+(use-package circadian
+  :config
+  (setq circadian-themes '((:sunrise . doom-gruvbox-light)
+                           (:sunset . (doom-dracula doom-gruvbox))))
+  (add-hook 'emacs-startup-hook #'circadian-setup)
+  (circadian-setup))
+``` 
+
+
+### Use with custom themes
+To use custom themes, install them from MELPA using
+e.g. [use-package](https://www.gnu.org/software/emacs/manual/html_mono/use-package.html)
+or [straight.el](https://github.com/radian-software/straight.el).
 
 Example usage featuring [hemera-themes](https://github.com/GuidoSchmidt/emacs-hemera-theme)
 and [nyx-theme](https://github.com/GuidoSchmidt/emacs-nyx-theme) (with use-package). Make sure
@@ -45,33 +99,16 @@ to use `:defer` keyword. Omitting it may lead to broken colors
 ;; make sure to use :defer keyword
 (use-package hemera-theme :ensure :defer)
 (use-package nyx-theme :ensure :defer)
-
-(use-package circadian
-  :ensure t
-  :config
-  (setq circadian-themes '(("8:00" . hemera)
-                           ("19:30" . nyx)))
-  (circadian-setup))
 ```
 
-##### Switching themes on sunrise & sunset
 
-Be sure to set your latitude and longitude (Get them e.g. at [latlong.net](https://www.latlong.net/)):
+### Verbose messages
+By default circadian will not log any messages. however for development or just
+getting more information, one can enable a more verbose message log:
 
 ```elisp
-;; Install additinal themes from melpa
-;; make sure to use :defer keyword
-(use-package apropospriate-theme :ensure :defer)
-(use-package nord-theme :ensure :defer)
+(setq circadian-verbose t)
 
-(use-package circadian
-  :ensure t
-  :config
-  (setq calendar-latitude 49.0)
-  (setq calendar-longitude 8.5)
-  (setq circadian-themes '((:sunrise . apropospriate-light)
-                           (:sunset  . nord)))
-  (circadian-setup))
 ```
 
 ---
@@ -107,7 +144,7 @@ e.g. I like to override any themes cursor color to a very bright color via:
 
 ---
 
-### Development
+### Development & Testing
 
 Install Emacs [cask](https://github.com/cask/cask) environment. On macOS you
 canr use [homebrew](https://brew.sh/) with: `brew install cask`.