From 8bdd9e3aaf1d029a2c47596837ad607a76563837 Mon Sep 17 00:00:00 2001 From: Dan <79267265+dansysanalyst@users.noreply.github.com> Date: Tue, 16 Jan 2024 15:49:03 +0100 Subject: [PATCH] [DOCS] Improve README and CONTRIBUTING GUIDE + Add Broken Link check (#1329) * Improve README * Improve CONTRIBUTING GUIDE * Add lychee for broken links check --- .github/lychee.toml | 116 +++++++++++++++++++++++++++++++++++ .github/workflows/lychee.yml | 22 +++++++ CONTRIBUTING.md | 78 ++++++++++++++++++++--- README.md | 77 ++++++++++++----------- 4 files changed, 251 insertions(+), 42 deletions(-) create mode 100644 .github/lychee.toml create mode 100644 .github/workflows/lychee.yml diff --git a/.github/lychee.toml b/.github/lychee.toml new file mode 100644 index 00000000..f477f914 --- /dev/null +++ b/.github/lychee.toml @@ -0,0 +1,116 @@ +############################# Display ############################# + +# Verbose program output +# Accepts log level: "error", "warn", "info", "debug", "trace" +#verbose = "warn" + +# Don't show interactive progress bar while checking links. +no_progress = false + +# Path to summary output file. +output = ".github/link_report.md" + +############################# Cache ############################### + +# Enable link caching. This can be helpful to avoid checking the same links on +# multiple runs. +cache = true + +# Discard all cached requests older than this duration. +max_cache_age = "1d" + +############################# Runtime ############################# + +# Number of threads to utilize. +# Defaults to number of cores available to the system if omitted. +threads = 2 + +# Maximum number of allowed redirects. +max_redirects = 10 + +# Maximum number of allowed retries before a link is declared dead. +max_retries = 2 + +# Maximum number of concurrent link checks. +max_concurrency = 14 + +############################# Requests ############################ + +# User agent to send with each request. +user_agent = "curl/7.83. 1" + +# Website timeout from connect to response finished. +timeout = 20 + +# Minimum wait time in seconds between retries of failed requests. +retry_wait_time = 2 + +# Comma-separated list of accepted status codes for valid links. +accept = [200, 429] + +# Proceed for server connections considered insecure (invalid TLS). +insecure = false + +# Only test links with the given schemes (e.g. https). +# Omit to check links with any scheme. +scheme = [ "https" ] + +# When links are available using HTTPS, treat HTTP links as errors. +require_https = false + +# Request method +method = "get" + +# Custom request headers +headers = [] + +# Remap URI matching pattern to different URI. +remap = [ "https://example.com http://example.invalid" ] + +# Base URL or website root directory to check relative URLs. +#base = "" + +# HTTP basic auth support. This will be the username and password passed to the +# authorization HTTP header. See +# +basic_auth = "user:pwd" + +############################# Exclusions ########################## + +# Skip missing input files (default is to error if they don't exist). +skip_missing = false + +# Check links inside `` and `
` blocks as well as Markdown code
+# blocks.
+include_verbatim = false
+
+# Ignore case of paths when matching glob patterns.
+glob_ignore_case = false
+
+# Exclude URLs and mail addresses from checking (supports regex).
+#exclude = [ '.*\.github.com\.*' ]
+# receiving forbidden but valid link, receiving timeout but valid link
+exclude = ['https://devsquad.com/', 'https://twitter.com/caneco', 'https://twitter.com/luanfreitasdev']
+
+# Exclude these filesystem paths from getting checked.
+#exclude_path = ["file/path/to/Ignore", "./other/file/path/to/Ignore"]
+
+# URLs to check (supports regex). Has preference over all excludes.
+#include = [ 'gist\.github\.com.*' ]
+
+# Exclude all private IPs from checking.
+# Equivalent to setting `exclude_private`, `exclude_link_local`, and
+# `exclude_loopback` to true.
+exclude_all_private = false
+
+# Exclude private IP address ranges from checking.
+exclude_private = false
+
+# Exclude link-local IP address range from checking.
+exclude_link_local = false
+
+# Exclude loopback IP address range and localhost from checking.
+exclude_loopback = false
+
+# Exclude all mail addresses from checking.
+exclude_mail = false
diff --git a/.github/workflows/lychee.yml b/.github/workflows/lychee.yml
new file mode 100644
index 00000000..252dc103
--- /dev/null
+++ b/.github/workflows/lychee.yml
@@ -0,0 +1,22 @@
+name: Check for broken Links
+on:
+  pull_request:
+    paths:
+      - '**.md'
+  push:
+    paths:
+      - '**.md'
+
+jobs:
+  linkChecker:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: πŸ”— Check Links
+        uses: lycheeverse/lychee-action@v1.6.1
+        with:
+          fail: true
+          args: --config .github/lychee.toml './**/*.md'
+        env:
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4e67a293..c065e405 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,13 +4,71 @@
 
 ------
 
-# How to contribute with ⚑ PowerGrid ⚑
+# PowerGrid Contribution Guide
 
-Thank you for your interesting in contributing with PowerGrid.
+`πŸ’“` **Thank you for your interest in contributing to PowerGrid.**
 
-If you have any questions, do not hesitate to reach the community in the repository [Discussions](https://github.com/Power-Components/livewire-powergrid/discussions) tab.
+Contributions are welcome and appreciated. There are many different ways to contribute to this project.
 
-## Steps
+## Contribution areas
+
+Here are some ways you can contribute and make an impact on PowerGrid.
+
+- [Community building](#community-building)
+- [Design](#design)
+- [Translation](#translation)
+- [Documentation](#documentation)
+- [Issues and Support](#issues-and-support)
+- [Demo Code](#demo-code)
+- [Code Contribution](#code-contribution)
+
+### Community building
+
+PowerGrid relies on a community of users and contributors. You can help build a stronger community by:
+
+- Participating in the [Discussions](https://github.com/Power-Components/livewire-powergrid/discussions) tab.
+- Write an article, tutorial, or record a YouTube video using PowerGrid.
+- Creating social media posts with PowerGrid content. You can talk about features, updates, and releases.
+- Sharing your code skills by helping newcomers and mentoring other users.
+
+### Design
+
+We try to grow the PowerGrid brand in a professional and impactful way.
+
+We appreciate your help with:
+
+- Creating artwork and improving the package's branding and presentation material.
+- Creating promotional and marketing materials for social media, video, and web content.
+- Providing or improving table components style.
+
+### Translation
+
+- PowerGrid is used by people in different parts of the world. You can help with translation (localization) and help the project better adapt to your community.
+
+### Documentation
+
+To be successful, an open-source project must have high-quality documentation.
+
+We appreciate your help with:
+
+- Try, review, and suggest changes to improve the user’s experience with any PowerGrid documentation content.
+- Maintain the README and CONTRIBUTING guides.
+- Adding, improving, or correcting the documentation directly in the [Power-Components/powergrid-doc](https://github.com/Power-Components/powergrid-doc) repository.
+
+## Demo Code
+
+- You can help by providing new use cases or improving the existing ones directly in the [Power-Components/powergrid-demo-misc](https://github.com/Power-Components/powergrid-demo-misc).
+
+### Issues and Support
+
+You can help the PowerGrid Team and contributors with handling open Issues and support requests.
+
+- Test, reproduce, and validate reported bugs.
+- Answer user questions in the [Issues](https://github.com/Power-Components/livewire-powergrid/issues) and [Discussions](https://github.com/Power-Components/livewire-powergrid/discussions) tabs.
+
+### Code Contribution
+
+ To build and test the code, follow the steps described in this section.
 
 1 .**Fork**
 
@@ -86,10 +144,16 @@ Please send clean and descriptive commits.
 
 7. **Pull Request**
 
-Open a Pull Request (PR) and use the template for detailing your changes and motivations. Please make only one change per Pull Request.
+Open a Pull Request (PR) and use the template to detail your changes and motivations. Please make only one change per Pull Request.
 
-If you never wrote a PR before, see this excellent [example](https://github.com/Power-Components/livewire-powergrid/pull/149) by [@vs0uz4](https://github.com/vs0uz4) for inspiration.
+If you have never written a PR before, see this excellent [example](https://github.com/Power-Components/livewire-powergrid/pull/149) by [@vs0uz4](https://github.com/vs0uz4) for inspiration.
 
 

 
- πŸ’“  Thank you for contributing!
+

+
+If you have any questions, do not hesitate to reach out to the community in the repository [Discussions](https://github.com/Power-Components/livewire-powergrid/discussions) tab.
+
+Thank you,
+
+⚑ The PowerGrid Team and [Contributors](../../contributors)
diff --git a/README.md b/README.md
index 4d5a7880..49552aa2 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,7 @@
     

     πŸ“š Documentation |
     πŸ”₯ Features |
+     πŸš€ Demo |
     ⌨️ Get started
 
 
@@ -20,32 +21,35 @@
 
 

 
-PowerGrid creates modern, powerful and easy to customize Datatables based on Laravel [Livewire](https://laravel-livewire.com) library.
+PowerGrid creates modern, powerful and easy-to-customize Datatables based on Laravel [Livewire](https://laravel-livewire.com) library.
 
 

 
-βž”  **Zero Configuration**: Tables have basic features activated by default.
+βž”  **Simple Configuration**: Tables have all basic features activated by default.
 
-βž”  **It fits your needs**: Extend and customize your table including components (checkbox, action buttons, editable fields), global search feature, column data filters and data export tool.
+βž”  **It fits your needs**: Extend and customize your table, including components (checkbox, action buttons, editable fields), global search feature, column data filters, and data export tool.
 
 βž”  **Full Stubs**: Table components include feature examples. Just uncomment some code, enter your data, and it works!
 
 

 
-

-    PowerGrid Dark Screenshot
-

+## πŸš€ Demo
 
-Dark mode:
-

-    PowerGrid Dark Screenshot
-

+Explore the Demo showcasing PowerGrid's main features across multiple use cases.
 
 

 
-## πŸš€ Instant Demo
+`β˜€οΈ` Light mode:
+
+

+    PowerGrid Light Screenshot
+

+
+`πŸŒ™` Dark mode:
 
-### [Online Demo](https://demo.livewire-powergrid.com) (tailwind)
+

+    PowerGrid Dark Screenshot
+

 
 ## Features
 
@@ -55,7 +59,7 @@ With PowerGrid you get right out of the box:
 
 - **Column Sorting**
 
-- **Column Sum, Count & Average in Header/Footer**
+- **Column Sum, Count and Average in Header/Footer**
 
 - **Pagination**
 
@@ -65,7 +69,7 @@ With PowerGrid you get right out of the box:
 
 - **Bulk Actions**
 
-- **Action Rules: Conditionally disable, hide and modify Action Buttons, Checkboxes and rows**
+- **Action Rules: Conditionally disable, hide, and modify Action Buttons, Checkboxes and rows**
 
 - **Toggle button**
 
@@ -87,54 +91,57 @@ With PowerGrid you get right out of the box:
 
 

 
- ![Laravel Livewire Tables](https://github.com/Power-Components/powergrid-doc/blob/main/docs/_media/example.gif?raw=true)
-
 ------
 
-# Get started
+## Get started
 
-## 1. Requirements
+### 1. Requirements
 
 - PHP 8.1+
-- [Laravel 10+](https://laravel.com/docs/9.x/installation)
+- [Laravel 10+](https://laravel.com/docs/installation)
 - [Livewire 3.0x](https://livewire.laravel.com)
 - [Tailwind 3x](https://tailwindcss.com/docs/guides/laravel) or [Bootstrap 5](https://getbootstrap.com/docs/5.0/getting-started/introduction/)
 
 

 
-## 2. Install
+### 2. Install
+
+Require PowerGrid via [composer](https://getcomposer.org).
 
 ```bash
 composer require power-components/livewire-powergrid
 ```
 
-Please follow the steps indicated in our [Documentation - Install](https://livewire-powergrid.com/get-started/install.html) page.
+Then, follow the steps indicated in our documentation's [Install](https://livewire-powergrid.com/get-started/install.html) page.
 
 

 
-## 3. Support
+## Support & Community
 
-For questions, issues, bug reports and feature requests, please use our [Issues](https://github.com/Power-Components/livewire-powergrid/issues).
+`πŸ‘₯` **Interact with the PowerGrid community at our [Discussions](https://github.com/Power-Components/livewire-powergrid/discussions) tab.**
 
-Before submitting a new request, please look into our previous issues.
+You can share ideas, find questions and answers, and collaborate with other PowerGrid users.
 
-Verify if your bug/question or feature request has been previously submitted.
+

+
+`πŸ›Ÿ` **For technical inquiries, bug reports, and feature requests, please use the [Issues](https://github.com/Power-Components/livewire-powergrid/issues) tab.**
+
+Please look into our previous Issues and Discussions before submitting a new issue.
 
 

 
-## 4. How to contribute
+## Contribute
 
-We appreciate your interest in contributing with PowerGrid.
+`πŸ™` **You can help PowerGrid in a number of ways; contributing goes beyond writing code.**
 
-Please read the [Contributing Guide](https://github.com/Power-Components/livewire-powergrid/blob/main/CONTRIBUTING.md).
+Please read the [Contributing Guide](https://github.com/Power-Components/livewire-powergrid/blob/main/CONTRIBUTING.md) to see what kind of contributions you can make and what steps you should follow.
 
 

 
-## 5. Credits
-
-Created by: [Luan Freitas](https://twitter.com/luanfreitasdev) and [@DanSysAnalyst](https://github.com/dansysanalyst)
+## Credits
 
-- [Contributors](../../contributors)
+- Created by [Luan Freitas](https://twitter.com/luanfreitasdev) and [@DanSysAnalyst](https://github.com/dansysanalyst)
+- [All Contributors](../../contributors)
 - Logo & artwork by [Caneco](https://twitter.com/caneco)
 
 

@@ -143,14 +150,14 @@ Created by: [Luan Freitas](https://twitter.com/luanfreitasdev) and [@DanSysAnaly
 

   
   
-    DevSquad
+    DevSquad
   
 

 
 

 

 
-
Supported by:

+
With the support of:

 

   
   
@@ -164,4 +171,4 @@ Created by: [Luan Freitas](https://twitter.com/luanfreitasdev) and [@DanSysAnaly
 
 

 
-Notice of Non-Affiliation and Disclaimer: Livewire PowerGrid is not affiliated, associated, endorsed by, or in any way officially connected with the Laravel Livewire - copyright by Caleb Porzio.
+Notice of Non-Affiliation and Disclaimer: Livewire PowerGrid is not affiliated with, associated with, endorsed by, or in any way officially connected with the Laravel Livewire - copyright by Caleb Porzio.