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

feat: rewrite all documentation (#4)

Browse Source 
Closes #3

Reviewed-on: https://codeberg.org/nhcarrigan/docs/pulls/4
Co-authored-by: Naomi Carrigan <commits@nhcarrigan.com>
Co-committed-by: Naomi Carrigan <commits@nhcarrigan.com>
This commit is contained in:
Naomi Carrigan
2024-07-08 07:56:24 +00:00
committed by Naomi the Technomancer
parent a356ffb402
commit 77a888b6bd
36 changed files with 5713 additions and 839 deletions
Download Patch File Download Diff File Expand all files Collapse all files

616
docs/contributing.md
View File

@ -1,136 +1,598 @@
# Contributing
> [!TIP]
> This document provides a high-level overview of contributing to our projects. Check with each project's documentation for more specific or supplemental instructions, if needed.
**Effective 7 July 2024**
Please ensure all pull requests and contributions comply with the [Developer Certificate of Origin](https://developercertificate.org/).
## 1. Scope and General Contribution Guidelines
> [!NOTE]
> All contributions to our projects will be licensed under our [global license](/license.md)
### 1.1 Overview
## Setting Up Your Code
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.
First, fork the repository to your own account. Then use `git clone <url>` to bring your forked repository down to your local machine (remember to get the URL for _your_ repository, not the original). Optionally, use `git remote add upstream <url>` to add the original repository as the upstream (this is helpful for keeping your fork up-to-date).
### 1.2 Project-Specific Instructions
## Claiming an Issue
While these guidelines apply broadly, individual projects may have unique requirements or processes. Always refer to the specific project's documentation for:
All of our issues are open to contributors! If you see an open issue you would like to work on, please comment on the issue so we may assign it to you.
- Supplemental instructions
- Project-specific workflows
- Coding standards
- Testing requirements
- Other relevant information
> [!NOTE]
> Assigned issues that have not had any activity in a week will be unassigned.
In case of any discrepancy between this document and project-specific guidelines, the project-specific instructions take precedence.
If an issue is already assigned, that means someone has expressed interest in working on it. We encourage you to reach out to them and collaborate on a PR together!
### 1.3 Commit Signing Requirements
We use special labels to help categorise issues. Feel free to [browse our breakdown of the labels](/labels.md).
All commits must be cryptographically signed using either GPG or SSH. This requirement serves to verify the authenticity and integrity of your contributions.
## Working on your issue
- 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.
Before starting work, we highly recommend ensuring that your forked version is up to date. If you set the `upstream` as mentioned in [Setting Up Your Code](#setting-up-your-code), run these commands in your terminal (with the terminal pointed at the root directory of your local files):
By signing your commit, you are certifying that:
- `git fetch upstream` - this gets the current state of the original repo, without pulling down the changes to your local machine.
- `git reset --hard upstream/main` - this resets the state of your local files to match the current state of the original repo.
- `git push -f` - this forces the changes to your forked repo (thus making it match the original)
- 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.
> [!NOTE]
> You will lose any changes you are currently working on. Do this with care.
### 1.4 Contributor Covenant
Next, use `git checkout -b <branchname>` to create a new branch for your work. It's always a good idea to avoid committing changes directly to your `main` branch - this keeps it clean and avoids errors when updating (above).
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).
Branch names should follow a convention of `scope/description` where:
### 1.5 Licensing of Contributions
- `scope` is the nature of the changes (eg. `feat` for a new feature, or `docs` for documentation update). This should match the scope of the related issue.
- `description` is a brief description of your changes, such as `update-contribs` for updating the contributing guidelines.
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.
Now you are free to work on your code! When you are satisfied with your changes, you can commit them with `git commit -s -m "message"`, where:
- Our global software license: Naomi's Public License
- Full text of the license: https://docs.nhcarrigan.com/#/license
- `-s` flag signs the commit, to verify the connection with your GitHub account.
- `-m` flag sets up the commit message.
- `message` is the commit message: a brief (50 character max) message describing what the commit changes.
### 1.6 Intellectual Property
> [!TIP]
> If you aren't sure which package manager to use, you can reach out to us in our [chat server](https://chat.nhcarrigan.com).
By contributing to our projects, you affirm that:
### Installing Packages
- 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.
Use `pnpm install` to install all current packages.
### 1.7 Legal Compliance
### Adding Packages
Ensure all contributions comply with relevant laws and regulations, including export controls and data protection laws.
`pnpm install` will allow you to add a new package.
### 1.8 Acceptance of Contributions
When adding a new package, you should use the `--save-exact` flag to pin the package version. The CI will check for unpinned versions when you open a PR.
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.
If the package is only for development (working on the project), and not needed for production (running the project), you should _also_ use the `--save-dev` flag to add the package to the `devDependencies` section of the `package.json` file.
## 2. Secrets Management
For example:
### 2.1 Overview
```bash
pnpm i --save-dev --save-exact @types/naomi # Adds a dev dependency
pnpm i --save-exact naomi # Adds a production dependency
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.
```
### Oops! I used `npm` when I should have used `pnpm`
### 5.7 Testing Your Changes
No worries! A quick note that if you ran `npm install` or `npm ci`, then `pnpm` will ignore the installed packages. You will need to run the following commands to get back in sync:
- 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
rm -rf package-lock.json node_modules
pnpm install
git push -u origin <branchname>
```
## Testing Changes
- `-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
> [!NOTE]
> Make sure to follow the steps above to check which package manager the project uses, and use the appropriate commands.
2. Ensure the push is successful and your changes appear in your forked repository on Codeberg.
Many of our projects will have continuous integration (CI) checks that run on a pull request. To ensure your changes will pass, you can often test these locally.
### 6.2 Creating the Pull Request
If the project has a `package.json` file, check for the following entries in the `scripts` property:
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.
- `build` - Running `pnpm run build` will confirm that a project successfully compiles. This is common in our TypeScript projects.
- `lint` - Running `pnpm run lint` will ensure that the code style is correct.
- `start` - Running `pnpm start` will confirm that the project boots up successfully.
- `test` - Running `pnpm test` will ensure that the unit and functional tests all pass.
### 6.3 Filling Out the Pull Request
You can also check the `.github/workflows` directory for `.yml` files. These files will describe the actual CI checks that run on your 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.
Ensuring these checks pass **before** submitting a pull request will streamline our review process.
### 6.4 Pull Request Best Practices
## Submitting a Pull Request
- 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.
Once you have all of your changes made and committed, you can push them to your forked repository! Use `git push -u origin <branchname>`, where:
### 6.5 After Submitting
- `-u` tells `git` to set the upstream (see below)
- `origin` tells `git` to push to your fork
- `branchname` tells `git` to push to a branch - this MUST match the name of the branch you created locally.
- 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.
> [!NOTE]
> By setting the upstream, any subsequent `push` commands can be done with `git push`, and it will be pushed to the same branch.
### 6.6 Updating Your Pull Request
Now you can open the pull request! You should see a quick option to do so appear at the top of your repository on GitHub. Click the "Pull Request" button to have GitHub automatically set up the pull request.
If you need to make changes to your pull request:
First, change the title of the pull request to match your branch name (following the conventions above!). Then, follow the instructions in the preset Pull Request template (make sure to complete any steps listed!).
1. Make the required changes in your local branch.
2. Commit the changes.
3. Push the new commits to your fork:
Congratulations! You've submitted your first pull request! We will review it as quickly as possible, so keep an eye out for approvals (or requested changes).
```bash
git push origin <branchname>
```
## Pull Request Reviews
4. The pull request will automatically update with your new commits.
All pull requests require a review before being merged. Most reviews will come from Naomi, but some projects may have additional staff who can submit reviews.
### 6.7 Pull Request Etiquette
If your pull request is approved, it will be merged and deployed depending on the project's deployment schedule and pipeline.
- 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.
If your pull request requires additional changes or information, we ask that you apply the changes promptly. Contributions with outstanding change requests that receive no activity within a week will be closed as stale.
### 6.8 Merging and Closing
## Other Contributions
- 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!
If you aren't comfortable with the codebase, or would like to contribute in other ways, we have options for that!
## 7. Pull Request Reviews
- Documentation Updates: You are always welcome to update our documentation (like this file!) if you see any typos or anything that can be clarified.
- Feature Requests: If you have ideas for new features or improvements, feel free to open an issue!
- Bug Reports: We rely on our users to help identify bugs - if you see something wrong, please let us know with an issue!
### 7.1 Review Process Overview
## Holopin Badges
- 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.
![Virtual badges featuring Naomi, Becca, and Rosalia](https://cdn.nhcarrigan.com/projects/holopin.png)
### 7.2 What Reviewers Look For
Contributors are eligible to receive digital [Holopin](https://www.holopin.io/@naomis-novas) badges for their contributions to our projects. To claim your badge, fill out the template in our [Discord community](https://chat.nhcarrigan.com)!
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.