nhcarrigan/docs
2
0
Fork 0
generated from nhcarrigan/template
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: convert to an astro application (!9)

Browse Source 
Reviewed-on: https://codeberg.org/nhcarrigan/docs/pulls/9
Co-authored-by: Naomi Carrigan <commits@nhcarrigan.com>
Co-committed-by: Naomi Carrigan <commits@nhcarrigan.com>
This commit is contained in:
Naomi Carrigan
2024-08-23 23:49:24 +00:00
committed by Naomi the Technomancer
parent 2898736099
commit 4cc44ae423
43 changed files with 4727 additions and 1368 deletions
Download Patch File Download Diff File Expand all files Collapse all files

600
src/content/docs/dev/contributing.md Normal file
View File

@ -0,0 +1,600 @@
---
title: Contributing Documentation
---
**Effective 7 July 2024**
## 1. Scope and General Contribution Guidelines
### 1.1 Overview
This document outlines the general guidelines for contributing to our projects. It serves as a high-level framework for all contributors, whether you're submitting code, documentation, or other forms of contribution.
### 1.2 Project-Specific Instructions
While these guidelines apply broadly, individual projects may have unique requirements or processes. Always refer to the specific project's documentation for:
- Supplemental instructions
- Project-specific workflows
- Coding standards
- Testing requirements
- Other relevant information
In case of any discrepancy between this document and project-specific guidelines, the project-specific instructions take precedence.
### 1.3 Commit Signing Requirements
All commits must be cryptographically signed using either GPG or SSH. This requirement serves to verify the authenticity and integrity of your contributions.
- For GPG signing, ensure your GPG key is associated with your GitHub or Codeberg account.
- For SSH signing, use a key linked to your GitHub or Codeberg account.
By signing your commit, you are certifying that:
- The commit adheres to our [Contributor Covenant](/covenant.md)
- You have the right to submit the contribution under our project license.
- You understand and agree to our contribution terms.
### 1.4 Contributor Covenant
All contributors are expected to adhere to our Contributor Covenant. The full text of the Contributor Covenant can be found in [its own document](/covenant.md).
### 1.5 Licensing of Contributions
All contributions to our projects, including but not limited to code, documentation, artwork, and other materials, will be licensed under our global software license. By submitting a contribution, you are agreeing to license your work under the terms of this license.
- Our global software license: Naomi's Public License
- Full text of the license: https://docs.nhcarrigan.com/#/license
### 1.6 Intellectual Property
By contributing to our projects, you affirm that:
- You own the copyright to your contribution or have authorization from the copyright owner to submit it under our license.
- Your contribution does not infringe on any third-party intellectual property rights.
- You grant us a perpetual, worldwide, non-exclusive, royalty-free license to use, modify, and distribute your contribution.
### 1.7 Legal Compliance
Ensure all contributions comply with relevant laws and regulations, including export controls and data protection laws.
### 1.8 Acceptance of Contributions
While we appreciate all contributions, we reserve the right to reject any contribution that doesn't meet our standards or align with our project goals. The project maintainers have final say on the inclusion of any contribution.
## 2. Secrets Management
### 2.1 Overview
Proper management of secrets is crucial for maintaining the security and integrity of our projects. We use 1Password as our centralized secrets management solution. This section outlines our policies and procedures for handling secrets.
### 2.2 General Policy
- Plain-text secrets should never be stored on personal machines, development environments, or our servers.
- All secrets should be stored and managed through 1Password.
### 2.3 1Password Setup and Usage
To work with secrets locally, you must set up the 1Password CLI (Command Line Interface) and integrate it with your 1Password desktop application.
#### 2.3.1 Setup Instructions
- Install the 1Password desktop application if you haven't already.
- Install the 1Password CLI. Instructions can be found at: https://developer.1password.com/docs/cli/get-started/
- Authenticate the CLI with your 1Password account.
- Configure your development environment to use the 1Password CLI for secret retrieval. https://developer.1password.com/docs/cli/secrets-environment-variables/
#### 2.3.2 Best Practices
- Use environment variables to store secrets retrieved from 1Password during runtime.
- Never log or display secrets in any form.
- Rotate secrets regularly.
### 2.4 Handling Secrets in Code
- Development environment variables should be set in `dev.env` - changes to this file should generally be excluded from your contributions.
- Use 1Password references instead of actual secret values in configuration files.
## 3. Setting Up Your Development Environment
### 3.1 Forking the Repository
1. Navigate to the original repository on Codeberg.
2. Click the "Fork" button in the upper right corner of the page.
3. Select your account as the destination for the fork.
4. Wait for Codeberg to create a copy of the repository in your account.
### 3.2 Cloning Your Fork
1. Go to your forked repository on Codeberg.
2. Click the "Code" button and copy the URL (HTTPS or SSH, depending on your setup).
3. Open your terminal or command prompt.
4. Navigate to the directory where you want to store the project.
5. Run the following command, replacing `<url>` with the URL you copied:
```
git clone <url>
```
6. Enter your GitHub credentials if prompted.
### 3.3 Setting Up the Upstream Remote
Adding the original repository as an upstream remote allows you to easily keep your fork up-to-date.
1. Change into the project directory:
```
cd <project-name>
```
2. Add the upstream remote:
```
git remote add upstream <original-repository-url>
```
Replace `<original-repository-url>` with the **git** URL of the original repository.
3. Verify the new remote:
```
git remote -v
```
You should see entries for both `origin` (your fork) and `upstream`.
### 3.4 Keeping Your Fork Up-to-Date
Regularly update your fork to incorporate changes from the upstream repository:
1. Fetch the branches and commits from the upstream repository:
```
git fetch upstream
```
2. Check out your fork's local main branch:
```
git checkout main
```
3. Merge changes from upstream/main into your local main branch:
```
git merge upstream/main
```
### 3.5 Troubleshooting
If you encounter any issues during setup:
1. Check the project's FAQ or troubleshooting guide (if available).
2. Search for similar issues in the project's issue tracker.
3. If the problem persists, open a new issue with detailed information about the problem and steps to reproduce it.
You can also reach out to us in our Discord server: https://chat.nhcarrigan.com
## 4. Claiming an Issue
### 4.1 Finding an Issue
1. Navigate to the project's issue tracker.
2. Browse open issues or use filters to find tasks that interest you.
3. Read the issue description thoroughly to understand the requirements and context.
### 4.2 Expressing Interest
1. If you find an issue you'd like to work on, comment on the issue expressing your interest.
2. Example comment: "I'm interested in working on this issue. May I be assigned to it?"
3. Wait for a project maintainer to respond and potentially assign the issue to you.
### 4.3 Issue Assignment
- Project maintainers will assign issues based on the order of interest and the contributor's experience level.
- Once assigned, you'll see your username in the "Assignees" section of the issue.
### 4.4 Already Assigned Issues
If an issue is already assigned:
1. Check the assignee and the last activity date.
2. If you're still interested in contributing, you can:
a. Comment on the issue expressing your interest to collaborate.
b. Reach out to the assigned person to offer assistance or discuss collaboration.
We encourage collaboration and pair programming on complex issues!
### 4.5 Working on the Issue
1. Once assigned, create a new branch in your fork for this specific issue.
2. Use a descriptive branch name, e.g., `fix/issue-123-button-alignment`.
3. Make your changes, committing regularly with clear, concise commit messages.
4. Push your changes to your fork.
5. Open a pull request when ready for review (see Pull Request Guidelines in section [X]).
### 4.6 Keeping the Community Updated
1. Provide regular updates on your progress in the issue comments.
2. If you encounter obstacles, don't hesitate to ask for help in the issue thread.
3. If you need to step away from an issue, please let us know so it can be reassigned if necessary.
### 4.7 Time Management
- Try to start working on the issue within a few days of assignment.
- If you haven't made progress within a week, the issue may be unassigned to keep the project moving forward.
- If you need more time, communicate this in the issue comments.
### 4.8 Multiple Issues
- We encourage focusing on one issue at a time to ensure quality and timely completion.
- If you want to work on multiple issues, please complete one before requesting assignment to another.
### 4.9 Issue Labels
Pay attention to issue labels for additional context:
- `good first issue`: Suitable for newcomers to the project or open source.
- `help wanted`: Issues where we're actively seeking community help.
- `staff only`: Issue that will require staff attention.
### 4.10 Respectful Communication
- Always be courteous and professional in issue discussions.
- Respect the decisions of project maintainers regarding issue assignments and priorities.
- If you disagree with something, express your thoughts constructively and be open to feedback.
## 5. Working on Your Issue
### 5.1 Updating Your Fork
Before starting work, ensure your forked version is up to date with the original repository. If you've set up the `upstream` remote as mentioned in Section 3, follow these steps:
1. Open your terminal and navigate to your project's root directory.
2. Run the following commands:
```bash
git fetch upstream
git merge upstream/main
```
### 5.2 Creating a New Branch
Always create a new branch for your work:
1. Create and switch to a new branch:
```bash
git checkout -b <branchname>
```
2. Follow the branch naming convention: `type/description`
- `type`: Indicates the nature of the changes (e.g., `feat`, `fix`, `docs`, `refactor`)
- `description`: A brief, hyphenated description of the changes
Examples:
- `feat/add-login-page`
- `fix/resolve-memory-leak`
- `docs/update-api-endpoints`
### 5.3 Making Changes
1. Make your code changes, following the project's coding standards and guidelines.
2. Regularly commit your changes with clear, concise messages.
3. Push your changes to your fork periodically:
```bash
git push origin <branchname>
```
### 5.4 Committing Changes
When you're ready to commit your changes:
1. Stage your changes:
```bash
git add .
```
Or stage specific files:
```bash
git add <file1> <file2>
```
2. Commit:
```bash
git commit
```
### 5.5 Commit Message Guidelines
- Follow Conventional Commit standards: `type(scope): description` such as `docs: update contributing guidelines`.
- Use the present tense ("Add feature" not "Added feature")
- Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
- Limit the first line to 50 characters or less
- Additonal information can be included in the body
- Do NOT reference issues/PRs in your commit
Example:
```
feat: add user authentication system
Implement JWT-based authentication for API endpoints.
```
### 5.7 Testing Your Changes
- Run any existing tests to ensure your changes haven't broken anything:
```bash
pnpm test # or the appropriate test command for your project
```
- Add new tests for your changes if applicable.
### 5.8 Documentation
- Update relevant documentation to reflect your changes.
- If you've added new features, include appropriate documentation.
### 5.9 Preparing for Pull Request
Before submitting a pull request:
1. Check that your code adheres to the project's style guidelines - the linters should pass.
1. Ensure the build succeeds.
1. Ensure all tests pass.
1. Review your changes and commit history.
If you're unsure about any part of the process or need help, don't hesitate to ask in our [chat server](https://chat.nhcarrigan.com). Our community is here to support you!
## 6. Submitting a Pull Request
### 6.1 Pushing Your Changes
1. Push your changes to your forked repository:
```bash
git push -u origin <branchname>
```
- `-u` sets the upstream, linking your local branch to the remote branch
- `origin` specifies your forked repository as the destination
- `<branchname>` is the name of your local branch
2. Ensure the push is successful and your changes appear in your forked repository on Codeberg.
### 6.2 Creating the Pull Request
1. Navigate to your forked repository on Codeberg.
2. You should see a prompt to create a pull request for your recently pushed branch. If not, click on the "Pull requests" tab and then the "New pull request" button.
3. Ensure the base repository is the original project repository and the base branch is `main`.
4. Select your fork as the head repository and your recently pushed branch as the compare branch.
### 6.3 Filling Out the Pull Request
1. Change the title of your pull request to be a conventional commit message summarising all changes in that PR
2. Fill out the pull request description with as much information as possible. This typically includes:
- A clear description of the changes
- The issue number(s) your pull request addresses
- Any additional context or explanations
3. If your changes include visual elements, consider adding screenshots or GIFs to illustrate the modifications.
### 6.4 Pull Request Best Practices
- Ensure your PR addresses only one issue or adds one feature. If you have made multiple unrelated changes, consider breaking them into separate pull requests.
- Double-check that all tests pass and there are no conflicts with the base branch.
- If your PR is a work in progress, mark it as a draft pull request.
### 6.5 After Submitting
- Keep an eye on your pull request for any comments, requests for changes, or approval.
- Be prepared to make additional commits to your branch if changes are requested.
### 6.6 Updating Your Pull Request
If you need to make changes to your pull request:
1. Make the required changes in your local branch.
2. Commit the changes.
3. Push the new commits to your fork:
```bash
git push origin <branchname>
```
4. The pull request will automatically update with your new commits.
### 6.7 Pull Request Etiquette
- Be patient. Maintainers are often managing multiple priorities.
- Be open to feedback and willing to make changes.
- Respond promptly to any questions or requests from reviewers.
- If there's a delay in your ability to respond or make requested changes, leave a comment explaining the situation.
### 6.8 Merging and Closing
- Once your pull request is approved, a maintainer will merge it into the main project.
- After merging, you can delete your branch from your fork if you won't be using it anymore.
- Celebrate your contribution to the project!
## 7. Pull Request Reviews
### 7.1 Review Process Overview
- All pull requests require at least one approved review before merging.
- Reviews are primarily conducted by Naomi, but some projects may have additional reviewers.
- The review process helps maintain code quality, consistency, and project standards.
### 7.2 What Reviewers Look For
Reviewers typically assess the following aspects:
1. Code quality and style adherence
2. Functionality and correctness of the implementation
3. Test coverage and passing status
4. Documentation updates (if applicable)
5. Adherence to project-specific guidelines
6. Potential impact on existing features or performance
### 7.3 Types of Review Outcomes
1. **Approved**: Your pull request is ready to be merged.
2. **Changes Requested**: Modifications or additional information is needed before approval.
3. **Commented**: The reviewer has provided feedback but hasn't explicitly approved or requested changes.
### 7.4 Responding to Review Feedback
If changes are requested:
1. Read all comments carefully to understand the requested modifications.
2. Ask for clarification if any feedback is unclear.
3. Make the necessary changes in your local branch.
4. Commit and push the changes to update your pull request.
5. Respond to each comment, explaining how you addressed the feedback or why you chose a different approach.
### 7.5 Best Practices for Handling Reviews
- Respond promptly to review comments (ideally within a few days).
- Be open to constructive criticism and willing to make changes.
- If you disagree with a suggestion, explain your reasoning politely and be open to discussion.
- Use the review process as a learning opportunity to improve your coding skills.
### 7.6 Timelines and Expectations
- We strive to review pull requests as quickly as possible, typically within a week.
- If your pull request requires changes, please address them promptly.
- Pull requests with outstanding change requests and no activity for a week may be closed as stale.
- If you need more time to address changes, communicate this in the pull request comments to prevent your contribution from being closed.
### 7.7 Multiple Iterations
- Complex changes may require multiple rounds of reviews and revisions.
- Stay engaged throughout the process and be patient if additional iterations are needed.
### 7.8 Learning from the Review Process
- Take note of common feedback to improve future contributions.
- Consider reviewing other pull requests to gain insights into the project's standards and practices.
### 7.9 After Approval
Once your pull request is approved:
1. It will be merged into the main branch by a project maintainer.
2. Depending on the project's deployment pipeline, your changes may be deployed immediately or as part of the next release cycle.
Thank you for providing that section. I'll expand and improve it to make it more comprehensive and encourage a wider range of contributions. Here's an enhanced version:
## 8. Other Contributions
We value all types of contributions, not just code. There are many ways to contribute to our project, regardless of your technical experience or comfort level with the codebase. Here are several ways you can make a meaningful impact:
### 8.1 Documentation Updates
Clear and accurate documentation is crucial for any project. You can help by:
- Fixing typos, grammatical errors, or unclear phrasing
- Adding examples or clarifying existing explanations
- Creating new documentation for undocumented features
- Improving README files, API documentation, or user guides
### 8.2 Feature Requests
Your ideas can help shape the future of the project. To suggest a new feature:
1. Check existing issues to ensure your idea hasn't been proposed
1. Clearly describe the feature and its potential benefits
1. If possible, outline how the feature might be implemented
> [!TIP]
> Consider discussing your idea in our community chat before creating an issue to gather initial feedback.
### 8.3 Bug Reports
Identifying and reporting bugs is a valuable contribution. When reporting a bug:
1. Search existing issues to avoid duplicates
1. Provide a clear, concise description of the problem
1. Include steps to reproduce the bug
1. Describe the expected behavior and what actually happened
1. If possible, include screenshots, error messages, or code samples
### 8.4 User Support
Helping other users is a great way to contribute to the community:
- Answer questions in our Discord server or other community platforms
- Share your knowledge and experiences with the project
- Guide new users through common issues or setup processes
- Create tutorials or blog posts about using the project
### 8.5 Design Contributions
If you have design skills, you can contribute by:
- Creating or improving project logos or icons
- Designing user interface mockups for new features
- Improving the overall user experience and accessibility
- Creating infographics or visual aids for documentation
### 8.6 Testing and Quality Assurance
Help improve the project's stability by:
- Testing new features or bug fixes
- Performing usability testing and providing feedback
- Writing or improving automated tests
- Identifying edge cases or potential security issues
### 8.7 Community Building
Foster a welcoming and inclusive community by:
- Welcoming new contributors and helping them get started
- Organizing or participating in community events or meetups
- Promoting the project on social media or relevant forums
- Helping to moderate community discussions
### 8.8 Internationalization and Localization
Make the project accessible to a global audience:
- Translate user interfaces
- Provide localized documentation
- Ensure the project supports multiple languages and cultures
### 8.9 Code Reviews
Even if you're not comfortable making code changes, you can:
- Review pull requests for documentation or small changes
- Provide feedback on proposed features or bug fixes
- Help ensure code style and convention consistency
### 8.10 Fundraising and Sponsorship
If you have connections or experience in this area:
- Help identify potential sponsors or grants
- Assist with writing grant applications
- Organize fundraising events or campaigns
Or even make a donation yourself!
### 8.11 Mentoring
Share your knowledge and experience:
- Mentor new contributors
- Create learning resources for the project
- Participate in or organize coding workshops related to the project
Remember, all contributions, big or small, are valuable to the project. Don't hesitate to get involved in any way you feel comfortable. If you have any questions about how to contribute or need help getting started, please reach out to us in our Discord server or through the project's communication channels.

44
src/content/docs/dev/covenant.md Normal file
View File

@ -0,0 +1,44 @@
---
title: nhcarrigan Contributor Covenant
---
**Effective 7 July 2024**
Copyright (C) 2024 nhcarrigan and its contributors.
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
## nhcarrigan Contributor Covenant 1.0
By making a contribution to this project I certify that:
<ol type="a">
<li>
I have read, understood, and agree to abide by the project's Code of Conduct in its entirety.
</li>
<li>
My contribution and participation align with the principles outlined in the Code of Conduct, including respect for all community members regardless of their identity or background.
</li>
<li>
I have the right to submit any code, documentation, or other content under the project's designated license.
</li>
<li>
If my contribution is based on previous work covered under an open source license, I have the right to submit that work with modifications under the project's license.
</li>
<li>
Any contribution provided to me by another person for submission to this project has been done so with certification of points <code>a</code> through <code>d</code>, and I have not modified it.
</li>
<li>
I understand that my contributions may be logged publicly, and that moderation actions taken in response to Code of Conduct violations may be recorded in the community's public moderation log.
</li>
<li>
I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.
</li>
<li>
I acknowledge that community leaders have the right and responsibility to remove, edit, or reject my contributions if they do not align with this certificate or the project's Code of Conduct.
</li>
<li>
I agree to release my contribution to nhcarrigan pursuant to the Terms of Service.
</li>
</ol>

3116
src/content/docs/dev/environment.md Normal file
View File

File diff suppressed because it is too large Load Diff

12
src/content/docs/dev/hall-of-fame.md Normal file
View File

@ -0,0 +1,12 @@
---
title: Security Hall of Fame
---
**Effective 7 July 2024**
## 1. Purpose
This document recognises the folks who have reported security vulnerabilities in our Applications pursuant to our [security policy](/security).
## 2. Recognitions
We extend our thanks to the following people for their efforts in keeping our users secure:

450
src/content/docs/dev/labels.md Normal file
View File

@ -0,0 +1,450 @@
---
title: Labels
---
**Effective 14 July 2024**
We use very specific labels to help categorise our issues. This page explains what each label means.
## 1. Contribution Labels
These are the most important. These labels indicate who is encouraged to make a pull request to resolve the issue.
### 1.1. `good first issue`
#### 1.1.1. Purpose
Identifies issues suitable for contributors who are new to the project.
#### 1.1.2. Characteristics
Does not require prior knowledge of the codebase. Issues with this label should include a detailed description of the implementation process.
#### 1.1.3. Expectations
Contributors are responsible for ensuring their work complies with the project's licensing terms and contribution guidelines.
### 1.2. `help wanted`
#### 1.2.1. Purpose
Indicates issues open for contribution from any interested party.
#### 1.2.2. Characteristics
Typically assumes prior experience with the codebase. As such, issues may not include a detailed implementation description.
#### 1.2.3. Expectations
Contributors should review and adhere to the project's contribution guidelines and code of conduct before submitting work on these issues.
### 1.3. `🔒 staff only`
#### 1.3.1. Purpose
Designates issues restricted to project maintainers or staff due to specific access requirements.
#### 1.3.2. Characteristics
Requires access to production infrastructure for proper testing and implementation. As such, limited to authorised project maintainers and staff.
#### 1.3.3. Expectations
Staff members working on these issues must adhere to all relevant confidentiality agreements, data protection policies, and internal security protocols.
### 1.4 Disclaimer
Labels are assigned based on the project maintainers' best judgment but may not guarantee the exact level of difficulty or access requirements for every contributor. Contributors should use their discretion and communicate with project maintainers if they have any doubts about their ability to address an issue or comply with any associated legal requirements.
## 2. Aspect Labels
These labels indicate the scope of the work required to resolve the issue.
### 2.1. `💻 aspect: code`
#### 2.1.1. Purpose
Identifies issues requiring changes to the project's codebase.
#### 2.1.2. Characteristics
Involves direct modification to the project's source code. Familiarity with the languages and libraries used is expected.
#### 2.1.3. Expectations
Contributors must ensure their code changes comply with the project's coding standards, license terms, and any applicable software patents or copyrights.
### 2.2. `🤖 aspect: dx`
#### 2.2.1. Purpose
Indicates issues related to improving the project's tooling and development workflow.
#### 2.2.2. Characteristics
May include changes to automated tests, development dependencies, build processes, etc. Understanding of the development workflows is expected.
#### 2.2.3. Expectations
Changes to tooling or dependencies must be compatible with the project's overall licensing strategy and not introduce conflicts with existing terms.
### 2.3. `🕹 aspect: interface`
#### 2.3.1. Purpose
Designates issues that affect the end-user's experience with the project.
#### 2.3.2. Characteristics
May require changes in the code, particularly in front-end components. Can include visual modifications like CSS changes or image updates. Understanding of the end-user experience expected.
#### 2.3.3. Expectations
Contributors must ensure they have the necessary rights to any visual assets introduced or modified. Changes should comply with accessibility standards and regulations where applicable.
### 2.4. `📄 aspect: text`
#### 2.4.1. Purpose
Identifies issues related to the project's documentation.
#### 2.4.2. Characteristics
Typically does not require code changes. Proficiency in technical writing is a must.
#### 2.4.3. Expectations
Contributors must ensure the accuracy of the information provided in documentation updates. Documentation changes should adhere to any applicable style guides and licensing terms.
### 2.5 Disclaimer
Aspect labels are assigned based on the primary focus of the issue but may not encompass all potential areas of impact. Contributors are encouraged to consider potential cross-aspect effects of their work and discuss these with project maintainers when in doubt. The project maintainers reserve the right to reassign aspect labels or request additional changes if the submitted work does not align with the intended scope of the issue.
## 3. Goal Labels
These labels indicate the primary objective of the issue, reflecting our project's modular approach. They help contributors understand the nature and scope of the changes they'll be making.
### 3.1. `⭐ goal: addition`
#### 3.1.1. Purpose
Identifies issues that involve adding a new feature to the project.
#### 3.1.2. Characteristics
Typically involves creating new code files. Understanding of how different modules in the project integrate with each other is expected.
#### 3.1.3. Expectations
Contributors must ensure that new features do not infringe on existing patents or copyrights. New code should be compatible with the project's existing license. If introducing third-party libraries or dependencies, their licenses must be compatible with the project's license.
### 3.2. `🛠 goal: fix`
#### 3.2.1. Purpose
Designates issues aimed at fixing bugs in the project.
#### 3.2.2. Characteristics
Typically involves editing code within existing files. Scope should be kept to the specific bug - separate contributions should be made for unrelated bugs.
#### 3.2.3. Expectations
Bug fixes should not introduce new legal issues or licensing conflicts. Contributors should document the nature of the bug and the fix for future reference and potential legal compliance (e.g., security vulnerabilities).
### 3.3. `✨ goal: improvement`
#### 3.3.1. Purpose
Indicates issues that expand upon or enhance existing features.
#### 3.3.2. Characteristics
Usually involves adding code to existing files. Scope should be kept to the existing feature.
#### 3.3.3. Expectations
Improvements should maintain compatibility with existing licenses and legal obligations. If the improvement significantly changes the functionality, consider if additional legal reviews or updates to user agreements are necessary.
### 3.4. Disclaimer
While goal labels provide guidance on the nature of the task, the actual work required may vary or expand beyond the initial scope. Contributors are encouraged to communicate with project maintainers if they believe a different approach or additional changes are necessary to achieve the goal. The project maintainers reserve the right to request modifications or additional work to ensure that contributions align with the project's goals, standards, and legal requirements.
## 4. Priority Labels
Priority labels indicate the importance assigned to specific issues by the project maintainers. These labels help guide resource allocation and set expectations for resolution timeframes.
### 4.1. `🟥 priority: critical`
#### 4.1.1. Purpose
Identifies issues requiring immediate attention due to their severe impact on project usability.
#### 4.1.2. Characteristics
Require urgent resolution to restore project functionality. Experience with the project is a must, to avoid delays from long review processes.
#### 4.1.3. Expectations
May involve security vulnerabilities or critical bugs that could lead to legal liabilities if not addressed promptly. Resolution of these issues may need to be reported to relevant stakeholders or authorities in certain cases (e.g., data protection regulators for security breaches).
### 4.2. `🟧 priority: high`
#### 4.2.1. Purpose
Designates important issues that, while not preventing basic functionality, are impeding further development.
#### 4.2.2. Characteristics
Not critical for current project operation but blocking future progress. Require prompt attention to unblock development efforts.
#### 4.2.3. Expectations
May involve compliance deadlines or contractual obligations that need to be met. Could impact project timelines, potentially affecting agreements with stakeholders or clients.
### 4.3. `🟨 priority: medium`
#### 4.3.1. Purpose
Indicates issues that need resolution as soon as possible but are not blocking other development.
#### 4.3.2. Characteristics
Important for project improvement but not critical for current functionality. Should be addressed in a timely manner but with less urgency than high-priority issues.
#### 4.3.3. Expectations
May involve improvements to user experience or accessibility, which could have legal implications if neglected long-term. Could relate to optimizations that affect performance guarantees or service level agreements.
### 4.4. `🟩 priority: low`
#### 4.4.1. Purpose
Represents issues that should be resolved but are not considered urgent.
#### 4.4.2. Characteristics
Desirable improvements or minor issues that don't significantly impact project functionality.
#### 4.4.3. Expectations
While not urgent, neglecting these issues over time could lead to technical debt or gradual degradation of project quality, potentially affecting long-term compliance or user satisfaction.
### 4.5. `🟪 priority: none`
#### 4.5.1. Purpose
Identifies "nice-to-have" issues that are not essential for project functionality or immediate development goals.
#### 4.5.2. Characteristics
Not critical enough to dedicate maintainer time for resolution. Often left for community contributors or future consideration.
#### 4.5.3. Expectations
While not prioritized, maintainers should periodically review these issues to ensure they haven't become more significant over time, potentially accruing legal or compliance risks.
### 4.6 Disclaimer
Priority labels reflect the project maintainers' current assessment and may be subject to change. The presence of a lower-priority label does not diminish the importance of the issue or the value of contributions addressing it. Contributors should communicate with maintainers if they believe an issue's priority should be reassessed due to new information or changing circumstances.
## 5. Status Labels
Status labels indicate the current stage of an issue in the project lifecycle. These labels help manage workflow and set expectations for contributors and users.
### 5.1. `🚦 status: awaiting triage`
#### 5.1.1. Purpose
Identifies newly created issues that have not yet been reviewed by the maintainer team.
#### 5.1.2. Characteristics
Should be applied to issues when they are opened.
#### 5.1.3. Expectations
Contributors should be aware that engaging with these issues is at their own discretion, as the project team has not yet evaluated them. Maintainers should establish a reasonable timeframe for initial triage to manage expectations and potential liability.
### 5.2. `🚧 status: blocked`
#### 5.2.1. Purpose
Indicates issues with a planned resolution that depend on the completion of another issue.
#### 5.2.2. Characteristics
Not yet ready for work but expected to be addressed in the future.
#### 5.2.3. Expectations
Maintainers should clearly document dependencies to avoid potential conflicts or misunderstandings. Regular review of blocked issues is advisable to prevent indefinite delays that could impact project timelines or contractual obligations.
### 5.3. `⛔️ status: discarded`
#### 5.3.1. Purpose
Designates issues that the project team does not intend to resolve.
#### 5.3.2. Characteristics
Typically applied to feature requests that don't align with project goals.
#### 5.3.3. Expectations
Clearly communicate the rationale for discarding issues to manage user expectations and maintain transparency. Ensure that discarded issues don't conflict with any promised features or contractual obligations.
### 5.4. `🙅 status: discontinued`
#### 5.4.1. Purpose
Applies to feature requests for projects in maintenance mode.
#### 5.4.2. Characteristics
Indicates no new features will be added, but bug fixes and support continue.
#### 5.4.3. Expectations
Clearly communicate the project's maintenance status to manage user expectations and potential liability. Ensure that discontinuation doesn't breach any ongoing support agreements or licenses.
### 5.5. `🏷 status: label work required`
#### 5.5.1. Purpose
Indicates issues that need proper labeling and categorization.
#### 5.5.2. Characteristics
May have ongoing discussions but lack appropriate classification.
#### 5.5.3. Expectations
Proper labeling is crucial for efficient project management and may have implications for compliance tracking and reporting. Establish clear guidelines for labeling to ensure consistency and avoid potential misunderstandings.
### 5.6. `🏁 status: ready for dev`
#### 5.6.1. Purpose
Signifies issues that are ready for contribution.
#### 5.6.2. Characteristics
May have an assigned contributor who has expressed interest.
#### 5.6.3. Expectations
Clearly communicate contribution guidelines and any legal requirements (e.g., Contributor Covenant) to potential contributors. Ensure that collaborative efforts are managed in compliance with project licenses and contributor agreements.
### 5.7. `🧹 status: ticket work required`
#### 5.7.1. Purpose
Indicates issues lacking sufficient information for proper triage.
#### 5.7.2. Characteristics
Often paired with Conversation Labels for further clarification.
#### 5.7.3. Expectations
Establish clear guidelines for required information to avoid potential misunderstandings or misdirected efforts. Be mindful of data privacy when requesting additional information from issue reporters.
### 5.8. Disclaimer
Status labels reflect the current assessment of the project team and may change as circumstances evolve. While the project team strives to maintain accurate status labels, contributors and users should communicate with maintainers if they notice any discrepancies or have questions about an issue's status.
## 6. Conversation Labels
Conversation labels indicate that an issue has received initial maintainer attention but requires further discussion or information before proceeding. These labels help manage communication and ensure all necessary information is gathered before taking action.
### 6.1. `💬 talk: discussion`
#### 6.1.1. Purpose
Identifies issues that are under active discussion but have not yet been accepted for resolution.
#### 6.1.2. Characteristics
Ongoing dialogue between maintainers, contributors, and/or users. May involve debates about feature requests, implementation strategies, or project direction.
#### 6.1.3. Expectations
Ensure discussions remain constructive and adhere to the project's code of conduct. Be cautious about making commitments or promises during discussions that could create legal obligations. Document key decisions and rationales to maintain transparency and provide a record for future reference.
### 6.2. `❓ talk: question`
#### 6.2.1. Purpose
Indicates issues waiting on additional information from the author for proper triage.
#### 6.2.2. Characteristics
Requires clarification or more details from the issue creator. Cannot proceed with triage or resolution until the requested information is provided.
#### 6.2.3. Expectations
Clearly communicate what information is needed and why it's necessary. Be mindful of data privacy when requesting additional information. Establish and communicate timeframes for expected responses to manage the issue lifecycle efficiently.
### 6.3. Disclaimer
Conversation labels indicate ongoing dialogue and do not guarantee that an issue will be implemented or resolved in a specific manner. Participants should understand that project priorities and decisions may change based on new information or project direction.
## 7. Pull Request Labels
Pull Request (PR) labels are used to indicate the current status of pull requests and guide contributors through the review and merge process.
### 7.1. `⚠️ pull: merge conflict`
#### 7.1.1. Purpose
Indicates that the pull request has conflicts with the target branch.
#### 7.1.2. Characteristics
Conflicts need to be resolved before the PR can be reviewed or merged. May require action from the original contributor or project maintainers.
#### 7.1.3. Expectations
Clearly communicate the responsibility for resolving conflicts (e.g., whether it's the contributor's or maintainer's role). Ensure that conflict resolution doesn't introduce unintended changes or legal issues (e.g., license conflicts).
### 7.2. `🔍 pull: ready for review`
#### 7.2.1. Purpose
Signifies that the pull request is not in draft mode and is awaiting maintainer review.
#### 7.2.2. Characteristics
PR has been submitted as complete and ready for evaluation. Maintainers should prioritize reviewing these PRs.
#### 7.2.3. Expectations
Ensure contributors understand that "ready for review" doesn't guarantee acceptance or merging. Maintain clear review criteria and communicate them to contributors.
### 7.3. `⏫ pull: requires update`
#### 7.3.1. Purpose
Indicates that the maintainer team has requested changes to the pull request.
#### 7.3.2. Characteristics
Feedback has been provided, and updates are needed before further review or merging. Requires action from the contributor to address the requested changes.
#### 7.3.3. Expectations
Clearly document requested changes to maintain transparency and avoid misunderstandings. Consider setting timeframes for updates to manage the PR lifecycle effectively.
### 7.4. Disclaimer
The presence of these labels does not guarantee that a pull request will be merged. All contributions must still meet the project's quality standards, guidelines, and legal requirements.
## 8. Continuous Improvement
We encourage all project participants to provide feedback on our labeling system. If you have suggestions for improvements or notice any inconsistencies, please reach out to us in our [chat server](https://chat.nhcarrigan.com).
## 9. Legal Notice
This labels documentation is provided for informational purposes and to facilitate project management. It does not constitute a legal agreement. All contributions to the project must comply with the project's license, contributor agreement (if applicable), and relevant laws and regulations.
By using these labels and participating in the project, you agree to abide by the project's code of conduct and contribution guidelines.

341
src/content/docs/dev/servers.md Normal file
View File

@ -0,0 +1,341 @@
---
title: Server Setup
---
**Effective 14 July 2024**
This document outlines how we set up our remote servers for running projects.
## 1. Provision a Server
We use DigitalOcean as our provider. Regardless of your choice, provision a new VPS using the **latest Ubunutu LTS version**. Add your `ssh` key AND Naomi's `ssh` key in the setup process.
## 2. Set Up User
You should never run applications on root. SSH into the new VPS to prepare your user.
### 2.1. Creating the User
You'll need to set a password for the `root` account first.
```bash
passwd
```
Once you have set a password, ensure that you have provided it to Naomi to store in the vault.
Create an `nhcarrigan` user for our organisation.
```bash
adduser nhcarrigan
```
Set a **different** password, and provide that to Naomi as well. For all of the user information, use the default blank values.
Add the new user to the sudoers file.
```bash
usermod -aG sudo nhcarrigan
```
Then sync the SSH keys so we can authenticate as that user.
```bash
rsync --archive --chown=nhcarrigan:nhcarrigan ~/.ssh /home/nhcarrigan
```
While you are there, set the timezone for the server to our business' local timezone.
```bash
sudo timedatectl set-timezone America/Los_Angeles
```
## 3. Preparing For Web Requests
To prepare the server to receive web requests, you'll need to follow a few steps.
### 3.1. SSL Certificate
> [!NOTE]
> If the Firewall has been set up, you'll need to temporarily allow port 80 for the certificate to generate.
We use LetsEncrypt to provision our SSL certificates. If it is not installed, install it with:
```bash
sudo snap install --classic certbot
```
Then link the snap to our `usr` directory.
```bash
sudo ln -s /snap/bin/certbot /usr/bin/certbot
```
Generate a certificate with:
```bash
sudo certbot certonly --standalone
```
And allow applications to read it:
```bash
sudo chmod -R a+rwx /etc/letsencrypt
```
When you need to renew the certificate:
```bash
sudo certbot renew
```
### 3.2. NGINX
All requests should be routed through NGINX. At no point should an application run directly on ports 80 or 443.
Install NGINX:
```bash
sudo apt-get install nginx
```
Edit the configuration file:
```bash
sudo emacs /etc/nginx/conf.d/server.conf
```
Use this template to set up a reverse proxy on the standard HTTPS port 443:
```nginx
server {
listen 443 ssl;
server_name subdomain.domain.tld;
ssl_certificate /etc/letsencrypt/live/subdomain.domain.tld/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/subdomain.domain.tld/privkey.pem;
location / {
proxy_set_header Host $host;
proxy_pass https://127.0.0.1:port;
proxy_redirect off;
}
}
```
Validate that the config is correct with:
```bash
sudo nginx -t
```
If so, restart NGINX to apply the changes:
```bash
sudo systemctl restart nginx
```
## 4. Securing the Server
We have a minimum level of security that is required on ALL of our servers. This section should not be treated as the best effort, but as the minimal requirements to comply with our policies.
### 4.1. Firewall
We use `ufw` as our firewall. First, enable the SSH port.
```bash
sudo ufw allow "OpenSSH"
```
Then, allow the standard HTTPS port and **deny** the standard HTTP port.
```bash
sudo ufw deny http
sudo ufw allow https
```
Enable the firewall. You may get dropped from the SSH connection.
```bash
sudo ufw enable
```
### 4.2. Fail2Ban
We also use Fail2Ban to block IP addresses which fail to make requests too often.
Install the tool:
```bash
sudo apt-get install fail2ban
```
Configure the NGINX jail in `/etc/fail2ban/jail.d/nginx-auth.conf`:
```ini
[nginx-auth]
enabled = true
filter = nginx-auth
logpath = /var/log/nginx/access.log
maxretry = 3
findtime = 86400
bantime = 86400
```
Configure the NGINX filter in `/etc/fail2ban/filter.d/nginx-auth.conf`:
```ini
[Definition]
failregex = ^<HOST> - .* \[.*\] ".*" (4\d{2}) .*$
```
Because we use Cloudflare, you'll need to grab the original IP for all requests. Start by creating a file to store Cloudflare's IPs.
```bash
sudo touch /etc/nginx/cloudflare_ips.conf
```
Then create your script:
```bash
nano ~/update_cf_ips.sh
```
```bash
#!/bin/bash
# Create a temporary file
temp_file=$(mktemp)
# Download IPv4 ranges and format each line
curl -s https://www.cloudflare.com/ips-v4 | while read ip; do
echo "set_real_ip_from $ip;" >> "$temp_file"
done
# Download IPv6 ranges and format each line
curl -s https://www.cloudflare.com/ips-v6 | while read ip; do
echo "set_real_ip_from $ip;" >> "$temp_file"
done
# Add the real_ip_header directive
echo "real_ip_header CF-Connecting-IP;" >> "$temp_file"
# Replace the old file with the new one
sudo mv "$temp_file" /etc/nginx/cloudflare_ips.conf
# Test Nginx configuration
sudo nginx -t
# If the test is successful, reload Nginx
if [ $? -eq 0 ]; then
sudo systemctl reload nginx
echo "Nginx configuration updated and reloaded successfully."
else
echo "Nginx configuration test failed. Please check your configuration."
fi
```
Make it executable and run it:
```bash
sudo chmod +x update_cf_ips.sh
sudo ./update_cf_ips.sh
```
If it runs as expected, set it up to run on a CRON.
```bash
sudo crontab -e
```
```bash
0 3 * * 1 ~/update_cf_ips.sh
```
Then, update the `/etc/nginx/nginx.conf` to use all of this new logic. This goes at the end of your `http` directive block.
```conf
# Look at the real IP, not the cloudflare IP.
include /etc/nginx/cloudflare_ips.conf;
log_format custom_format '$remote_addr - $remote_user [$time_local] '
'"$request" $status $body_bytes_sent '
'"$http_referer" "$http_user_agent" '
'"$http_x_forwarded_for"';
access_log /var/log/nginx/access.log custom_format;
```
Confirm the NGINX configuration is correct:
```bash
sudo nginx -t
```
Then restart everything.
```bash
sudo systemctl restart nginx
sudo systemctl restart fail2ban
```
To view banned IPs:
```bash
sudo fail2ban-client status nginx-auth
```
And to unban them:
```bash
sudo fail2ban-client set nginx-auth unbanip <ip>
```
## 5. Running a Project
Now you are ready to start running the project.
### 5.1. Node.js
Most of our projects will run on Node. For a new machine, you'll need to set that up.
We use `nvm` to manage Node versions. Fetch and run the install script:
```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.37.2/install.sh | bash
```
The script will automatically update the `.bashrc` file to load `nvm` into the PATH. Reload that:
```bash
source ~/.bashrc
```
Install the long-term support Node version.
```bash
nvm install --lts
```
This should automatically set it as the default. When updating, be sure to remove any older versions!
Finally, install `pnpm` as the package manager.
```bash
npm i -g pnpm
```
### 5.2. PM2
All of our processes run with PM2 to allow for monitoring and auto-restarts. You'll need to install it.
```bash
pnpm i -g pm2
```
To start a project, use this template:
```bash
pm2 start '<script>' --name '<name>'
```
Then run `pm2 save` to save the application list.