Docs overhaul #1099
Docs overhaul #1099
Conversation
Add Table of Contents Add Quick Start guide for Docker and Home Assistant Fix typo in line 67 (was 33) lits -> list Add Security & Privacy section Add FAQ Add Known Issues
Adding Contributor Covenant v2.1 with a special ethical clause specific to NetAlertX
Updated the page for better readability, additional information, and to add recent additions in this branch to it
Add Responsibility disclaimer Add TLDR Add more formatting Deep dives into configurations more specifically Adds responsible disclosure section
Add code pr template and docs pr template for conformity.
Adds templates for enhancements to differentiate enhancing existing features and adding whole new ones. Refactor/Code quality is mostly for dev/contributor use for doc purposes. Security report is essential and also directs them to reach out with sensitive details directly Translation requests added to allow additional accessibility to be requested as-needed and to allow prioritization based on need.
They'll find it if they want to see them.
WalkthroughThis update introduces a comprehensive set of documentation and community management improvements. It adds detailed GitHub issue and pull request templates, a Contributor Covenant Code of Conduct, expanded contributing guidelines, a significantly enhanced README, and a rewritten security guide. These changes aim to structure user contributions, clarify security practices, and foster a respectful, inclusive project environment. Changes
Sequence Diagram(s)sequenceDiagram
participant Contributor
participant GitHub
participant Maintainers
Contributor->>GitHub: Selects issue or PR template
GitHub->>Contributor: Presents structured form (template)
Contributor->>GitHub: Submits filled template
GitHub->>Maintainers: Notifies with labeled, structured issue/PR
Maintainers->>Contributor: Reviews and responds per guidelines
Poem
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (12)
.github/PULL_REQUEST_TEMPLATE/docs-pr-template.md (1)
24-31: Add an explicit “Preview / Rendered output” checkpoint
Before merging, reviewers often need to confirm that the markdown renders correctly (tables, admonitions, etc.). Adding a task-list item for this makes the expectation explicit and prevents broken formatting from slipping through.## ✅ Checklist ... - [ ] I'm open to feedback and suggestions +- [ ] I previewed the rendered page and verified there are no layout / formatting issues.github/PULL_REQUEST_TEMPLATE/code-pr-template.md (1)
17-25: Consider grouping rarely-used categories under a collapsibleDetails
block
The long list of checkboxes can overwhelm first-time contributors. Collapsing less common categories (e.g., CI, performance) keeps the template concise while preserving options..github/ISSUE_TEMPLATE/enhancement-request.yml (1)
28-33: Mark “willing to help” response as required
Knowing whether the reporter can assist implementation is valuable triage data. Making the checkbox mandatory avoids the “empty” state.- attributes: + attributes: label: Are you willing to help implement this? options: - label: "Yes" - label: "No" + required: true.github/ISSUE_TEMPLATE/translation-request.yml (1)
31-36: Setrequired: trueto capture contributor availability
As with the enhancement template, making this field required clarifies whether maintainers can expect help on the translation effort.- attributes: + attributes: label: Can you help with translation or review? options: - label: Yes - label: No + required: true.github/ISSUE_TEMPLATE/refactor-codequality-request.yml (1)
32-37: Require “can you help implement” selection
Consistency with other templates and better planning for maintainer bandwidth.- attributes: + attributes: label: Can you help implement this change? options: - label: Yes - label: No + required: true.github/ISSUE_TEMPLATE/security-report.yml (2)
10-10: Fix trailing spaces.Remove the trailing spaces at the end of line 10 to improve code cleanliness.
- We appreciate your responsible disclosure. + We appreciate your responsible disclosure.
26-26: Fix indentation issue.The indentation is incorrect - should be 4 spaces instead of 6 to match YAML formatting standards.
- - label: Yes, I have sent the details to jokob@duck.com + - label: Yes, I have sent the details to jokob@duck.comREADME.md (3)
117-117: Consider adding a comma for clarity.The sentence would read more clearly with a comma after "local".
-A: No. All scans and data remain local unless you set up cloud-based notifications. +A: No. All scans and data remain local, unless you set up cloud-based notifications.
120-120: Use "installation" instead of "install" as a noun."Install" is a verb; "installation" is the appropriate noun form.
-A: Yes! You can install it bare-metal. See the [bare metal install guide](https://github.com/jokob-sk/NetAlertX/blob/main/docs/HW_INSTALL.md). +A: Yes! You can install it bare-metal. See the [bare metal installation guide](https://github.com/jokob-sk/NetAlertX/blob/main/docs/HW_INSTALL.md).
123-123: Use "Back up" as a verb instead of "Backup"."Backup" is a noun; "Back up" is the verb form.
-A: In the `/config` volume, mapped in Docker. Backup this folder regularly. +A: In the `/config` volume, mapped in Docker. Back up this folder regularly.CODE_OF_CONDUCT.md (1)
63-63: Wrap bare URL in angle brackets.For better markdown formatting, bare URLs should be enclosed in angle brackets.
-reported to the community leaders responsible for enforcement at jokob@duck.com. +reported to the community leaders responsible for enforcement at <jokob@duck.com>.docs/SECURITY.md (1)
49-52: Specify language for the code block.Add a language identifier to the fenced code block for better syntax highlighting and clarity.
- ``` + ```ini SETPWD_enable_password=true SETPWD_password=your_secure_password -``` + ```
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (10)
.github/ISSUE_TEMPLATE/enhancement-request.yml(1 hunks).github/ISSUE_TEMPLATE/refactor-codequality-request.yml(1 hunks).github/ISSUE_TEMPLATE/security-report.yml(1 hunks).github/ISSUE_TEMPLATE/translation-request.yml(1 hunks).github/PULL_REQUEST_TEMPLATE/code-pr-template.md(1 hunks).github/PULL_REQUEST_TEMPLATE/docs-pr-template.md(1 hunks)CODE_OF_CONDUCT.md(1 hunks)CONTRIBUTING(1 hunks)README.md(3 hunks)docs/SECURITY.md(1 hunks)
🧰 Additional context used
🪛 YAMLlint (1.37.1)
.github/ISSUE_TEMPLATE/security-report.yml
[error] 10-10: trailing spaces
(trailing-spaces)
[warning] 26-26: wrong indentation: expected 4 but found 6
(indentation)
🪛 LanguageTool
CODE_OF_CONDUCT.md
[style] ~33-~33: Try using a synonym here to strengthen your wording.
Context: ...ind - Trolling, insulting or derogatory comments, and personal or political attacks - Pu...
(COMMENT_REMARK)
README.md
[uncategorized] ~117-~117: Possible missing comma found.
Context: ...t?** A: No. All scans and data remain local unless you set up cloud-based notificat...
(AI_HYDRA_LEO_MISSING_COMMA)
[grammar] ~120-~120: The word ‘install’ is not a noun.
Context: ...tall it bare-metal. See the [bare metal install guide](https://github.com/jokob-sk/NetA...
(A_INSTALL)
[grammar] ~123-~123: The word ‘Backup’ is a noun. Do you mean the verb “Back up”?
Context: ...the /config volume, mapped in Docker. Backup this folder regularly. ## 🐞 Known Is...
(SENT_START_BACKUP)
🪛 markdownlint-cli2 (0.17.2)
CODE_OF_CONDUCT.md
63-63: Bare URL used
null
(MD034, no-bare-urls)
docs/SECURITY.md
52-52: Fenced code blocks should have a language specified
null
(MD040, fenced-code-language)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: docker_dev
🔇 Additional comments (10)
.github/ISSUE_TEMPLATE/security-report.yml (1)
1-28: Excellent security template implementation.The template effectively guides users toward responsible disclosure by clearly warning against public posting and requiring confirmation of private reporting. The structure and content align well with security best practices.
CONTRIBUTING (1)
1-53: Comprehensive and well-structured contributing guide.The expanded contributing guidelines provide clear, actionable guidance for all types of contributors. The structure flows logically from issue reporting through PR submission, with helpful resources for newcomers and proper references to community standards.
README.md (3)
11-43: Excellent README enhancements.The addition of the table of contents, quick start section, and structured documentation significantly improves the user experience. The content is comprehensive and well-organized, making it much easier for users to get started and find the information they need.
96-106: Well-implemented security section.The security and privacy section effectively addresses user concerns about data handling and provides clear guidance on securing installations. This aligns well with the detailed security documentation in
docs/SECURITY.md.
108-134: Valuable FAQ and Known Issues sections.These sections proactively address common user questions and set appropriate expectations about limitations. This will reduce support burden and improve user satisfaction.
CODE_OF_CONDUCT.md (2)
69-77: Excellent project-specific ethical use clause.The addition of an ethical use clause is particularly appropriate for a network scanning tool like NetAlertX. This section clearly establishes expectations about authorized use and respects privacy and legal boundaries, which is crucial for maintaining the project's integrity.
1-137: Comprehensive and well-structured code of conduct.The code of conduct provides a solid foundation for community governance, combining the proven Contributor Covenant framework with thoughtful project-specific additions. The enforcement guidelines are clear and the ethical use clause is particularly valuable for this type of software.
docs/SECURITY.md (3)
1-102: Outstanding comprehensive security documentation.The security documentation is exceptionally well-structured and comprehensive. It effectively covers all critical aspects from responsibility disclaimers to specific hardening recommendations. The TL;DR section provides quick guidance while detailed sections offer thorough explanations. This significantly enhances the project's security posture and user guidance.
19-28: Excellent TL;DR security checklist.The key security recommendations section provides a clear, actionable checklist that users can quickly reference. This format makes security best practices more accessible and likely to be followed.
92-99: Well-implemented responsible disclosure process.The responsible disclosure section provides a clear, private channel for security vulnerability reporting that aligns with the GitHub security issue template. This creates a proper security feedback loop for the project.
| ## ✅ Checklist | ||
|
|
||
| - [ ] I have read the [Contribution Guidelines](https://github.com/jokob-sk/NetAlertX/blob/main/docs/CONTRIBUTING.md) | ||
| - [ ] I have tested my changes locally | ||
| - [ ] I have updated relevant documentation (if applicable) | ||
| - [ ] I have verified my changes do not break existing behavior | ||
| - [ ] I am willing to respond to requested changes and feedback |
There was a problem hiding this comment.
Replace hard-coded external repo link with a relative link
The current link points to jokob-sk/NetAlertX, which is unrelated and will confuse contributors working in this repository. Use a relative path so the template works in forks as well.
- [ ] I have read the [Contribution Guidelines](https://github.com/jokob-sk/NetAlertX/blob/main/docs/CONTRIBUTING.md)
+ [ ] I have read the [Contribution Guidelines](../CONTRIBUTING.md)Committable suggestion skipped: line range outside the PR's diff.
🤖 Prompt for AI Agents
In .github/PULL_REQUEST_TEMPLATE/code-pr-template.md around lines 41 to 47, the
checklist contains a hard-coded external link to the Contribution Guidelines in
the jokob-sk/NetAlertX repository. Replace this absolute URL with a relative
link pointing to the CONTRIBUTING.md file within the current repository to
ensure the link works correctly in forks and avoids confusion for contributors.
There was a problem hiding this comment.
I mean, it is relevant, but I also agree relative links are better than hardcoded for our uses here.
There was a problem hiding this comment.
🧩 Analysis chain
@slammingprogramming You're absolutely right! Relative links are much better for this use case since they'll work correctly in forks and don't break if the repository name changes.
Let me check the actual file structure to provide the correct relative path:
🏁 Script executed:
#!/bin/bash
# Find the CONTRIBUTING file to determine its exact location
fd -t f "CONTRIBUTING" .
Length of output: 39
Perfect! The CONTRIBUTING file is located at the root of the repository. From the PR template's location (.github/PULL_REQUEST_TEMPLATE/code-pr-template.md), the correct relative path would be:
- [ ] I have read the [Contribution Guidelines](https://github.com/jokob-sk/NetAlertX/blob/main/docs/CONTRIBUTING.md)
+ [ ] I have read the [Contribution Guidelines](../../CONTRIBUTING)This relative path will work perfectly in forks and won't break if the repository structure changes. The ../../ navigates up two directory levels from the template location to reach the root where the CONTRIBUTING file is located.
|
Happy to try to merge this if happy @slammingprogramming 🙂 I don't know how you an write this much so quickly |
|
When I have some time I'll send you a screenshot of my wpm on one of those sites lol |
|
As for merge we can do that also I'm implementing the nitpicks it mentioned cause now that I have seen I cannot unsee. But we can go ahead for merge. |
2 participants
📚 Documentation Update
This PR adds and updates some documentation to improve standardization, readability, and maintains the format of existing docs.
📝 What’s Changed?
🔍 Related Issue(s)
Didn't bother making one first. I'm wild like that.
✅ Checklist
mkdocs.ymlif necessary🙋 Additional Notes
I made these with love but let me know if they need any more attention. I did make every effort to ensure updated and added docs align with the style of other docs.
Summary by CodeRabbit