agate

Simple gemini server for static files
git clone https://github.com/mbrubeck/agate.git
Log | Files | Refs | README

CONTRIBUTING.md (5900B)

      1 # Contributing
      2 
      3 ## Contents
      4 
      5 - [Introduction](#introduction)
      6 - [Code of Conduct](#code-of-conduct)
      7 - [Reporting Bugs and Suggesting Improvements](#reporting-bugs-and-suggesting-improvements)
      8 - [Contribution Workflow](#contribution-workflow)
      9 - [Quality Standards](#quality-standards)
     10 - [Release Process](#release-process)
     11 
     12 ## Introduction
     13 
     14 Hello, and welcome to the contributing guide for Agate!
     15 
     16 Agate is mostly maintained in the spare time of contributors, so be patient if it takes a bit longer to respond.
     17 By following this guide you'll make it easier for us to address your issues or incorporate your contributions.
     18 
     19 We look forward to working with you!
     20 
     21 ## Code of Conduct
     22 
     23 Please note that this project is released with a [Code of Conduct](./CODE_OF_CONDUCT.md).
     24 By participating in this project you agree to abide by its terms.
     25 
     26 ## Reporting security issues
     27 
     28 If you find a security issue, please disclose it to Johann150 privately, e.g. per [email](mailto:johann+agate@qwertqwefsday.eu). If you know how to fix the issue, please follow the contribution workflow as if you do not use GitHub, regardless of if you actually use it. I.e. patches should also be submitted privately.
     29 
     30 An effort will be made to respond to such issues quickly, at least responding with a "read receipt". If you do not hear back anything regarding the security issue within three days, try contacting other maintainers listed in the Cargo.toml file or on crates.io for this crate.
     31 
     32 There are no bug bounties. You can not expect any compensation apart from attribution in the changelog and/or for any patches you supply.
     33 
     34 ## Reporting Bugs and Suggesting Improvements
     35 
     36 Bugs (unwanted behaviour) and suggested improvements are tracked as [GitHub issues][github-issues].
     37 Before reporting an issue, please check the following points:
     38 
     39 1. The issue is caused by Agate itself and not by how it is used.
     40   Have a look at the documentation if you are not sure.
     41   If you cannot connect to Agate via the Internet, please try connecting with a client on the same machine to make sure the problem is not caused by intermediate infrastructure.
     42 1. Your issue has not already been reported by someone else.
     43   Please look through the open issues in the [issue tracker][github-issues].
     44 
     45 When reporting an issue, please add as much relevant information as possible.
     46 This will help developers and maintainers to resolve your issue. Some things you might consider:
     47 
     48 * Use a descriptive title.
     49 * State which version you are using (use a version tag like `v2.4.1` or the commit hash).
     50 * If you are using tools provided with agate (like a startup script), please also state that.
     51 * Describe how the problem can be reproduced.
     52 * Explain what exactly is the problem and what you expect instead.
     53 
     54 [github-issues]: https://github.com/mbrubeck/agate/issues
     55 
     56 ## Contribution Workflow
     57 
     58 Follow these steps to contribute to the project:
     59 
     60 ### If you use git but not GitHub:
     61 
     62 1. Clone the repository where you want.
     63 1. Make the appropriate changes, meeting all [contribution quality standards](#quality-standards).
     64 1. Update the changelog with any added, removed, changed, or fixed functionality. Adhere to the changelog format.
     65 1. Mail the patches or a pull request to [Johann150](mailto:johann+agate@qwertqwefsday.eu).
     66     - Patches are prefered for small changes.
     67     - Pull requests have to contain the repository URL and branch name.
     68 1. You will be notified of any further actions (e.g. requested changes, merged) by the same address you sent from. So please make sure you can receive mail on that address.
     69 
     70 ### If you use GitHub:
     71 
     72 1. Make a fork of the [Agate repository][agate-repo].
     73 1. Within your fork, create a branch for your contribution. Use a meaningful name.
     74 1. Create your contribution, meeting all [contribution quality standards](#quality-standards).
     75 1. Update the changelog with any added, removed, changed, or fixed functionality. Adhere to the changelog format.
     76 1. [Create a pull request][create-a-pr] against the `master` branch of the repository.
     77 1. Once the pull request is reviewed and CI passes, it will be merged.
     78 
     79 [agate-repo]: https://github.com/mbrubeck/agate
     80 [create-a-pr]: https://help.github.com/articles/creating-a-pull-request-from-a-fork/
     81 
     82 ## Quality Standards
     83 
     84 Most quality and style standards are checked automatically by the CI build.
     85 Contributions should:
     86 
     87 - Separate each **logical change** into its own commit.
     88 - Ensure the code compiles correctly, if you can also run `cargo clippy`.
     89 - Format code with `cargo fmt`.
     90 - Avoid adding `unsafe` code.
     91   If it is necessary, provide an explanatory comment on any `unsafe` block explaining its rationale and why it's safe.
     92 - Add a descriptive message for each commit.
     93   Follow [these commit message guidelines][commit-messages].
     94 - Document your pull requests.
     95   Include the reasoning behind each change, and the testing done.
     96 
     97 [commit-messages]: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
     98 
     99 ## Release Process
    100 (This is only relevant if you are a maintainer.)
    101 
    102 1. Bump the version number appropriately. (Update `Cargo.lock` too!)
    103 1. Run `cargo package` to make sure everything compiles correctly.
    104 1. Update the changelog with the new version ranges.
    105 1. Update agate's homepage (`content/index.gmi`) with changes to the README and CHANGELOG
    106 1. Add a git tag for the version, e.g. with `git tag v2.4.1`.
    107 1. Push the changelog commit and tag to the repository.
    108     Upon detecting the push of a tag beginning with "v", CI should start building the prebuilt binaries.
    109     These binaries will be uploaded to a new draft GitHub release with the same name as the version tag. (You need push access to see it).
    110 1. Run `cargo publish` to publish to [crates.io](https://crates.io/crates/agate).
    111 1. Fill the GitHub release text with the appropriate entries from the changelog.
    112 1. Wait for the binary compilation to finish.
    113 1. Publish the GitHub release.