From f6feedb72b9b5c1b61ee383fc49e8b7111a6cb81 Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Thu, 1 Sep 2022 20:45:11 +0300 Subject: fix: name of contributing page Sponsored-by: author --- contributing.md | 151 ------------------------------------------------------ contributing.mdwn | 151 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 151 insertions(+), 151 deletions(-) delete mode 100644 contributing.md create mode 100644 contributing.mdwn diff --git a/contributing.md b/contributing.md deleted file mode 100644 index dde5d5d..0000000 --- a/contributing.md +++ /dev/null @@ -1,151 +0,0 @@ -[[!meta title="Contributing to Obnam"]] - -[[!toc]] - -The Obnam project welcomes contributions. If you want to help Obnam -become better, you can. There are many ways to contribute that don't -involve writing code. - -* improve the documentation - - fix typos or grammar - - clarify some part - - provide a helpful diagram - - write missing parts of the documentation -* improve the website - - fix typos or grammar - - fix a layout problem - - suggest a helpful link - - make a stylish logo? -* try out the software and report your back your experiences - - what went well? what could be improved? -* help others who have trouble with the software - - on IRC, Matrix, or on the issue tracker -* help the developers understand what you need - - document your use case -* fix a bug -* add a missing feature - -We co-ordinate our work via the gitlab.com [issue tracker][]. Using it -requires an account on the site: if that's a problem for you, please -get in touch and we may be able to arrange something. - -[issue tracker]: https://gitlab.com/obnam/obnam/-/issues -[web site repository]: https://gitlab.com/obnam/obnam.org -[code repository]: https://gitlab.com/obnam/obnam - -# Set up to change the web site - -To contribute a change to the web site, you set up like this: - -* Fork the [web site repostiory][]. - - you will need your own account on gitlab.com for this -* Clone the code from your fork. -* Make a new git branch and start making changes. -* Commit everything. -* Push your changes back to your fork. -* Make a merge request from your fork to the main project. - -You can, if you want to, test your changes by building a local copy of -the website, but that's not required. - -# Set up to change the code - -If you want to make a contribution by changing the code, you can set -up an environment following these steps: - -* Install the [Rust][] language toolchain, using [rustup][]. - - using a toolchain packaged for, say, Debian, may also work, but may - be old -* Install any other build dependencies, as described in the [README][] - and [debian/control] files. -* Fork the [code repository][]: - - you will need your own account on gitlab.com for this -* Clone the code from your fork. -* Run `./check` to make sure everything works. -* Make a new git branch and start making changes. - - make sure `./check` works with your changes -* Commit everything. -* Push your changes back to your fork. -* Make a merge request from your fork to the main project. - -[Rust]: https://www.rust-lang.org/ -[rustup]: https://www.rust-lang.org/tools/install -[README]: https://gitlab.com/obnam/obnam/-/blob/main/README.md -[debian/control]: https://gitlab.com/obnam/obnam/-/blob/main/debian/control -[gitlab]: https://gitlab.com/obnam/obnam/ - -# Getting Obnam to change so you can do what you want to do - -Sometimes it happens you want Obnam to do something that it doesn't -quite know how to do. Here's some advice for that situation. - -* For any substantial discussions, we prefer the issue tracker over - chat systems. Chat systems are great for quick questions, but - they're also ephemeral and only help the people who happen to be - present at the time. The issue tracker lasts longer, and allows - long-form replies and taking time to respond in depth. - -* When suggesting or contributing a new feature, please always start - by explaining the thing you want to achieve. "I want to back up a a - historic computer's disk with a file system that isn't supported by - Linux" is a better start than sending a patch for backing up raw - disks. It's easier to judge a change fairly if the need for it is - clear. - -* If you contribute a functional change, please also change the - automated test suite to verify the changed functionality changes. If - you're not sure how to do that, please ask, and we'll help. We rely - on our test suite to be able to make large changes rapidly and - confidently. (Adding tests for bugs, when they're fixed, would be - nice too, but we don't insist on that.) - -Some caveats so you know what to expect: - -* Obnam is a hobby project. It might take a while for us to respond. - Please be patient. However, if you open an issue, and haven't heard - back in a week, ping us on the issue or via a chat system. We try to - be prompt, but sometimes work and life get in the way of working on - hobby projects. - - -# Code review process - -We use [gitlab.com](https://gitlab.com/larswirzenius/obnam) for code -hosting, and their merge request feature for reviewing changes. -However, most changes are currently made by Lars, the founder of the -project, and he is also the only one who can merge. Reviewing one's -own changes is less than ideal, as well as boring. Thus, to open the -door to code reviews by other people, the following process is in -place: - -* Lars will push changes, and for each change set a value for N, which - may be different for each change. -* Lars will wait for N days for comments, and if nothing has been - raised that would prevent a merge, and if discussion isn't - continuing, Lars will merge. -* Comments on merge requests on gitlab.com will be open: anyone will - be able to comment. -* Lars may update the MR based on feedback, applying his best - judgment. - -Typical values for N will be: - -* 0 for typo fixes and similar low-impact changes, or fixes to - urgent high-impact issues (immediate self-merge) -* 1 for other urgent changes -* 3 for most changes – this will be the default -* 5 for changes likely to be controversial or affecting security - related code - -Lars will advertise the merge requests via various channels. The hope -is that this will eventually attract people to do reviews. As time -goes by, and trust is built, some of those people will get the -"approve" or "merge" privilege. The "approve" privilege allows marking -a merge request as "approved", allowing someone else to merge. The -"merge" one will allow telling GitLab to actually merge the change, -closing the merge request. - -Merge requests by others will follow the same process. If nobody else -reviews a change, Lars will do that. - -This process will be adjusted as needed as time goes by. diff --git a/contributing.mdwn b/contributing.mdwn new file mode 100644 index 0000000..dde5d5d --- /dev/null +++ b/contributing.mdwn @@ -0,0 +1,151 @@ +[[!meta title="Contributing to Obnam"]] + +[[!toc]] + +The Obnam project welcomes contributions. If you want to help Obnam +become better, you can. There are many ways to contribute that don't +involve writing code. + +* improve the documentation + - fix typos or grammar + - clarify some part + - provide a helpful diagram + - write missing parts of the documentation +* improve the website + - fix typos or grammar + - fix a layout problem + - suggest a helpful link + - make a stylish logo? +* try out the software and report your back your experiences + - what went well? what could be improved? +* help others who have trouble with the software + - on IRC, Matrix, or on the issue tracker +* help the developers understand what you need + - document your use case +* fix a bug +* add a missing feature + +We co-ordinate our work via the gitlab.com [issue tracker][]. Using it +requires an account on the site: if that's a problem for you, please +get in touch and we may be able to arrange something. + +[issue tracker]: https://gitlab.com/obnam/obnam/-/issues +[web site repository]: https://gitlab.com/obnam/obnam.org +[code repository]: https://gitlab.com/obnam/obnam + +# Set up to change the web site + +To contribute a change to the web site, you set up like this: + +* Fork the [web site repostiory][]. + - you will need your own account on gitlab.com for this +* Clone the code from your fork. +* Make a new git branch and start making changes. +* Commit everything. +* Push your changes back to your fork. +* Make a merge request from your fork to the main project. + +You can, if you want to, test your changes by building a local copy of +the website, but that's not required. + +# Set up to change the code + +If you want to make a contribution by changing the code, you can set +up an environment following these steps: + +* Install the [Rust][] language toolchain, using [rustup][]. + - using a toolchain packaged for, say, Debian, may also work, but may + be old +* Install any other build dependencies, as described in the [README][] + and [debian/control] files. +* Fork the [code repository][]: + - you will need your own account on gitlab.com for this +* Clone the code from your fork. +* Run `./check` to make sure everything works. +* Make a new git branch and start making changes. + - make sure `./check` works with your changes +* Commit everything. +* Push your changes back to your fork. +* Make a merge request from your fork to the main project. + +[Rust]: https://www.rust-lang.org/ +[rustup]: https://www.rust-lang.org/tools/install +[README]: https://gitlab.com/obnam/obnam/-/blob/main/README.md +[debian/control]: https://gitlab.com/obnam/obnam/-/blob/main/debian/control +[gitlab]: https://gitlab.com/obnam/obnam/ + +# Getting Obnam to change so you can do what you want to do + +Sometimes it happens you want Obnam to do something that it doesn't +quite know how to do. Here's some advice for that situation. + +* For any substantial discussions, we prefer the issue tracker over + chat systems. Chat systems are great for quick questions, but + they're also ephemeral and only help the people who happen to be + present at the time. The issue tracker lasts longer, and allows + long-form replies and taking time to respond in depth. + +* When suggesting or contributing a new feature, please always start + by explaining the thing you want to achieve. "I want to back up a a + historic computer's disk with a file system that isn't supported by + Linux" is a better start than sending a patch for backing up raw + disks. It's easier to judge a change fairly if the need for it is + clear. + +* If you contribute a functional change, please also change the + automated test suite to verify the changed functionality changes. If + you're not sure how to do that, please ask, and we'll help. We rely + on our test suite to be able to make large changes rapidly and + confidently. (Adding tests for bugs, when they're fixed, would be + nice too, but we don't insist on that.) + +Some caveats so you know what to expect: + +* Obnam is a hobby project. It might take a while for us to respond. + Please be patient. However, if you open an issue, and haven't heard + back in a week, ping us on the issue or via a chat system. We try to + be prompt, but sometimes work and life get in the way of working on + hobby projects. + + +# Code review process + +We use [gitlab.com](https://gitlab.com/larswirzenius/obnam) for code +hosting, and their merge request feature for reviewing changes. +However, most changes are currently made by Lars, the founder of the +project, and he is also the only one who can merge. Reviewing one's +own changes is less than ideal, as well as boring. Thus, to open the +door to code reviews by other people, the following process is in +place: + +* Lars will push changes, and for each change set a value for N, which + may be different for each change. +* Lars will wait for N days for comments, and if nothing has been + raised that would prevent a merge, and if discussion isn't + continuing, Lars will merge. +* Comments on merge requests on gitlab.com will be open: anyone will + be able to comment. +* Lars may update the MR based on feedback, applying his best + judgment. + +Typical values for N will be: + +* 0 for typo fixes and similar low-impact changes, or fixes to + urgent high-impact issues (immediate self-merge) +* 1 for other urgent changes +* 3 for most changes – this will be the default +* 5 for changes likely to be controversial or affecting security + related code + +Lars will advertise the merge requests via various channels. The hope +is that this will eventually attract people to do reviews. As time +goes by, and trust is built, some of those people will get the +"approve" or "merge" privilege. The "approve" privilege allows marking +a merge request as "approved", allowing someone else to merge. The +"merge" one will allow telling GitLab to actually merge the change, +closing the merge request. + +Merge requests by others will follow the same process. If nobody else +reviews a change, Lars will do that. + +This process will be adjusted as needed as time goes by. -- cgit v1.2.1