From 386cda66797ba11c4a78fe3caffb7616a3d2fca1 Mon Sep 17 00:00:00 2001 From: Suyog Tandel Date: Sun, 22 Feb 2026 14:27:29 +0530 Subject: [PATCH] chore(docs): Add contribution and issue templates, and contributing guide --- .github/CONTRIBUTING.md | 85 +++++++++++++++++++++++++++ .github/ISSUE_TEMPLATE.md | 66 +++++++++++++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 45 +++++++++++++++ README.md | 99 ++++++++++++++++---------------- 4 files changed, 247 insertions(+), 48 deletions(-) create mode 100644 .github/CONTRIBUTING.md create mode 100644 .github/ISSUE_TEMPLATE.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..407d359 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,85 @@ +# CONTRIBUTING.md + +First off, thank you for considering contributing to PicoForge! It's contributors like you that help make this project better for everyone. We deeply appreciate your time, effort, and interest in improving the tool. + +This document outlines the guidelines and workflow for contributing to the `picoforge` project. + + + +## Table of Contents + +1. [Code Acquisition (Source Cloning)](#1-code-acquisition-source-cloning) +2. [Basic Workflow](#2-basic-workflow) +3. [Code Style and Formatting](#3-code-style-and-formatting) +4. [Pull Request (PR) Submission Workflow](#4-pull-request-pr-submission-workflow) +5. [Review Process](#5-review-process) +6. [Communication Channels](#6-communication-channels-discuss-before-contributing) +7. [Code of Conduct](#7-code-of-conduct) +8. [Legal Notice](#8-legal-notice) + + + +## 1. Code Acquisition (Source Cloning) + +The primary repository is hosted on GitHub, but a read-only mirror is available. **Mirrors can only be used to clone the source code locally.** + +| Platform | URL | Purpose | +| :---------------------------- | :----------------------------------------------- | :-------------------------------- | +| **GitHub (Primary Source)** | `https://github.com/librekeys/picoforge.git` | Required for Contribution Forking | +| **Personal Mirror** | `https://git.suyogtandel.in/LibreKeys/picoforge` | Read-only viewing and cloning | + + + +## 2. Basic Workflow + +1. Fork the repository +2. Create a feature branch (`git checkout -b feature/amazing-feature`) +3. Commit your changes (`git commit -m 'Add amazing feature'`) +4. Push to the branch (`git push origin feature/amazing-feature`) +5. Open a Pull Request directly against the `main` branch. + + + +## 3. Code Style and Formatting + +- Follow standard Rust coding guidelines and match the existing code style of the PicoForge source code. +- Always use `cargo fmt` to automatically format your code before committing. +- Write clear, concise commit messages. +- Always remember to update documentation for new features. +- Test on multiple platforms when possible before publishing changes. + + + +## 4. Pull Request (PR) Submission Workflow + +- Before submitting your Pull Request, please ensure you have followed the checklist in our [Pull Request Template](PULL_REQUEST_TEMPLATE.md). +- Ensure that any install or build dependencies are removed before the end of the layer when doing a build, and verify that your code compiles successfully. +- Before proceeding, please review the [general steps for completing a pull request](#2-basic-workflow) in this repository. +- One of the key aspects of validating a pull request is verifying that it doesn't break any existing work. Ensure that your code compiles, passes all tests, and that any CI checks run without errors. +- When opening a Pull Request (PR), please explicitly ask for a review from one of the maintainers. Depending on what is changed in the PR, tag either the repository or package maintainer. +- For more info on the project, please check [README.md](../README.md). + + + +## 5. Review Process + +- Our reviewers and maintainers contribute their free time to this project. Please be patient, as it may take a few days for them to review, approve, or request changes on your PR. We genuinely appreciate your work and want to ensure it integrates well into the project. +- In case your PR goes unanswered for more than 2 weeks, feel free to tag the main maintainer (`@lockedmutex`) in the comments to bring it to their attention. + + + +## 6. Communication Channels (Discuss Before Contributing) + +Matrix is our most preferred option for direct communication, followed by Discord. +- **Matrix**: [Join our Matrix room](https://matrix.to/#/%23librekeys:matrix.org) +- **Discord**: [Join our Discord server](https://discord.gg/6wYBpSHJY2) +- **Discussions**: [GitHub Discussions](https://github.com/librekeys/picoforge/discussions) +- **Issues**: [GitHub Issues](https://github.com/librekeys/picoforge/issues) + +## 7. Code of Conduct + +We are committed to providing a welcoming and inspiring community for all. Please be polite and respectful in all your interactions with the project. + +## 8. Legal Notice + +By contributing code, documentation, or other assets to the PicoForge project, the contributor agrees that the content is 100% authored by them, that they have the necessary rights to the content, and that the content may be provided under the project's existing license. diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md new file mode 100644 index 0000000..ae519bb --- /dev/null +++ b/.github/ISSUE_TEMPLATE.md @@ -0,0 +1,66 @@ +# Submitting an issue + +Thank you for taking the time to report an issue or suggest a feature for PicoForge! + +Please read our [Contributing Guidelines](CONTRIBUTING.md) to understand how to get involved. If you want to work on an existing issue or a new feature, it is highly recommended to discuss it beforehand to ensure there is no conflicting code or duplicate effort. + + + +## Before submitting an issue, check the following checklist: + +- [ ] I have checked the [Troubleshooting Guide](../docs/Troubleshooting.md) +- [ ] I have searched the existing issues to ensure this has not already been reported +- [ ] I am using the latest version of PicoForge +- [ ] I am using the the latest supported version of picofido/picofido2 + +## The Problem + + + +### What are the steps to reproduce this issue? + + + +1. +2. +3. + +### Expected Results + + + +### Actual Results + + + +### Is there anything else you would like to report? + + + +## Environment + + + +- **OS:** (e.g. Linux, Windows 10, macOS) +- **App Version:** (e.g. 0.1.0, or commit hash if building from source) +- **FIDO Firmware Version:** (if applicable) +- **Device Variant:** (e.g. Raspberry Pi Pico 2, ESP32-S3) + +## Logs + + + +### Console Logs +```text +Paste terminal output here +``` + +### In-App Logs + diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..88df039 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,45 @@ +# Pull Request Process + + + +### Checklist + +Ensure that your pull request has followed all the steps below: + +- [ ] Code compiles without errors +- [ ] Code is formatted using `cargo fmt` +- [ ] All tests are passing (skip if no tests exist) +- [ ] Extended the documentation with the changes made in the code (Optional) +- [ ] Added myself to the CREDITS.md file +- [ ] Requested review from one of the maintainers + +### Description + +Please describe the changes in this pull request. What does it do? Why is it needed? + +### Proposed changes + +Why should this pull request be accepted? What problem does it solve? +(If it resolves a previous issue, please link to that issue here.) + +### Types of changes + +Please check the relevant types of changes this PR introduces: + +- [ ] Bug fix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] Documentation update +- [ ] Refactoring / Code style change +- [ ] Add packaging for a new platform in the release workflows + +### UI Changes (Optional) + + +- Screenshots / Videos: diff --git a/README.md b/README.md index 7037819..628f950 100644 --- a/README.md +++ b/README.md @@ -186,59 +186,61 @@ cargo run ``` picoforge/ -├── Cargo.toml # Rust dependencies and project metadata -├── Cargo.lock # Rust dependency lock file -├── src/ # Source code -│ ├── main.rs # Application entry point -│ ├── logging.rs # Logging infrastructure -│ ├── device/ # Device communication logic -│ │ ├── fido/ # FIDO implementation -│ │ ├── rescue/ # Rescue mode handling -│ │ ├── io.rs # IO Utilities -│ │ ├── error.rs # Device error types -│ │ ├── mod.rs -│ │ └── types.rs # Device data types -│ └── ui/ # GPUI Frontend -│ ├── components/ # Reusable UI components -│ ├── views/ # View definitions -│ ├── assets.rs # Asset loader -│ ├── colors.rs # Color definitions -│ ├── rootview.rs # Root view container -│ ├── ui_types.rs # UI-specific types -│ └── mod.rs -├── data/ # Application data -│ ├── in.suyogtandel.picoforge.desktop -│ └── screenshots/ # Screenshots -├── docs/ # Documentation -├── static/ # Static assets (icons) -├── flake.nix # Nix flake configuration -├── default.nix # Nix development shell -├── shell.nix # Nix development shell -├── picoforge.spec # RPM Spec file -├── package.nix # Nix package definition -├── ci.nix # CI configuration for cachix -├── rustfmt.toml # Rust formatting configuration -├── CREDITS.md # Credits -└── LICENSE # License +├── Cargo.toml # Rust dependencies and project metadata +├── Cargo.lock # Rust dependency lock file +├── Packager.toml # Configuration for cargo-packager +├── src/ # Source code +│ ├── main.rs # Application entry point +│ ├── logging.rs # Logging infrastructure +│ ├── error.rs # Global application error types +│ ├── device/ # Device communication logic +│ │ ├── fido/ # FIDO implementation +│ │ ├── rescue/ # Rescue mode handling +│ │ ├── io.rs # IO Utilities +│ │ ├── mod.rs # Device module declaration +│ │ └── types.rs # Device data types +│ └── ui/ # GPUI Frontend +│ ├── components/ # Reusable UI components +│ ├── views/ # View definitions +│ ├── assets.rs # Asset loader +│ ├── colors.rs # Color definitions +│ ├── rootview.rs # Root view container +│ ├── types.rs # UI-specific types +│ └── mod.rs # UI module declaration +├── data/ # Application data +│ ├── in.suyogtandel.picoforge.desktop # Linux desktop entry file +│ └── screenshots/ # Screenshots for documentation +├── docs/ # Project documentation/wiki files +│ ├── Building.md # Instructions for building from source +│ ├── Home.md # Wiki home page +│ ├── Installation.md # Installation guide +│ └── Troubleshooting.md # Troubleshooting common issues +├── maintainers/ # Scripts and resources for package maintainers +│ └── scripts/ # Utility scripts for automating maintenance tasks +│ ├── update.nix # Nix update script configuration +│ └── update.py # Update script implementation +├── static/ # Static application assets +│ ├── appIcons/ # App icons in various sizes and formats +│ └── icons/ # Internal SVG icons used by the GPUI frontend +├── themes/ # Application themes +│ └── picoforge-zinc.json # Zinc theme configuration file +├── flake.nix # Nix flake configuration +├── flake.lock # Nix flake lock file +├── default.nix # Nix package definition/shell +├── shell.nix # Nix development shell +├── picoforge.spec # RPM Spec file +├── package.nix # Nix package definition +├── ci.nix # CI configuration for cachix +├── rustfmt.toml # Rust formatting configuration +├── CREDITS.md # Credits +└── LICENSE # License ``` ## Contributing -Contributions are welcome (REALLY NEEDED, PLEASE HELP ME)! follow these steps: +Contributions are welcome (REALLY NEEDED, PLEASE HELP US)! -1. Fork the repository -2. Create a feature branch (`git checkout -b feature/amazing-feature`) -3. Commit your changes (`git commit -m 'Add amazing feature'`) -4. Push to the branch (`git push origin feature/amazing-feature`) -5. Open a Pull Request - -### Development Guidelines - -- Follow Rust best practices -- Use `cargo fmt` to format the code -- Write clear commit messages -- Update documentation for new features -- Test on multiple platforms when possible +Please check the [CONTRIBUTING.md](.github/CONTRIBUTING.md) file for the full contribution process and development guidelines. ## License @@ -249,6 +251,7 @@ See [LICENSE](LICENSE) for full details. ## Repository Maintainers - **Suyog Tandel** ([@lockedmutex](https://github.com/lockedmutex)) +- **Lab-8916100448256** ([@Lab-8916100448256](https://github.com/Lab-8916100448256)) - Co-Maintainer ## Package Maintainers