Add contribution guideline
This commit is contained in:
Tim Byrne
parent
19c6eb6009
commit
f3e4c7d140
1 changed files with 364 additions and 0 deletions
364
.github/CONTRIBUTING.md
vendored
Normal file
364
.github/CONTRIBUTING.md
vendored
Normal file
|
|
@ -0,0 +1,364 @@
|
|||
# Introduction
|
||||
|
||||
Thank you for considering contributing to **yadm**. I develop this project in my
|
||||
limited spare time, so help is very appreciated.
|
||||
|
||||
All contributors must follow our [Code of Conduct][conduct]. Please make sure
|
||||
you are welcoming and friendly during your interactions, and report any
|
||||
unacceptable behavior to <yadm@yadm.io>.
|
||||
|
||||
Contributions can take many forms, and often don’t require writing code—maybe
|
||||
something could be documented more clearly, maybe a feature could be more
|
||||
helpful, maybe installation could be easier. Help is welcome in any of these
|
||||
areas.
|
||||
|
||||
To contribute, you can:
|
||||
|
||||
* Report [bugs](#reporting-a-bug)
|
||||
* Request [features/enhancements](#suggesting-a-feature-or-enhancement)
|
||||
* Contribute changes to [code, tests](#contributing-code), and [documentation](#improving-documentation)
|
||||
* Maintain installation [packages](#maintaining-packages)
|
||||
* Help other users by [answering support questions](#answering-support-questions)
|
||||
|
||||
# Reporting a bug
|
||||
|
||||
Notice something amiss? You’re already helping by reporting the problem! Bugs
|
||||
are tracked using GitHub issues. Here are some steps you can take to help
|
||||
problems get fixed quickly and effectively:
|
||||
|
||||
### Before submitting an issue
|
||||
|
||||
Please take a quick look to see whether the problem has been reported already
|
||||
(there’s a list of [open issues][open-issues]). You can try the search function
|
||||
with some related terms for a cursory check. If you do find a previous report,
|
||||
please add a comment there instead of opening a new issue.
|
||||
|
||||
### Security issues
|
||||
|
||||
If you have found a security vulnerability, do **NOT** open an issue.
|
||||
|
||||
Any security issues should be emailed directly to <yadm@yadm.io>. In order to
|
||||
determine whether you are dealing with a security issue, ask yourself these two
|
||||
questions:
|
||||
|
||||
* Can I access something that's not mine, or something I shouldn't have access to?
|
||||
* Can I disable something for other people?
|
||||
|
||||
If the answer to either of those two questions is "yes", then you're probably
|
||||
dealing with a security issue.
|
||||
|
||||
### Submitting a (great) bug report
|
||||
|
||||
Choose the "[Bug report][new-bug]" issue type.
|
||||
|
||||
Pick a descriptive title that clearly identifies the issue.
|
||||
|
||||
Describe the steps that led to the problem so that we can go through the same
|
||||
sequence. A clear set of steps to reproduce the problem is key to fixing an
|
||||
issue. If possible, attach a [`script.gz`](#attaching-a-scriptgz) to the bug
|
||||
report.
|
||||
|
||||
Describe what you had expected and how that differed from what happened, and
|
||||
possibly, why.
|
||||
|
||||
Include the version numbers of your operating system, of **yadm**, and of Git.
|
||||
|
||||
### Attaching a script.gz
|
||||
|
||||
Consider trying to reproduce the bug inside a docker container using the
|
||||
[yadm/testbed][testbed] docker image. Doing so will greatly increase the
|
||||
likelihood of the problem being fixed.
|
||||
|
||||
The easiest way to start this container, is to clone the [TheLocehiliosan/yadm
|
||||
repo][yadm-repo], and use the `scripthost` make target. _(You will need `make`
|
||||
and `docker` installed.)_
|
||||
|
||||
For example:
|
||||
|
||||
```text
|
||||
$ git clone https://github.com/TheLocehiliosan/yadm.git
|
||||
$ cd yadm
|
||||
$ make scripthost version=1.12.0
|
||||
Starting scripthost version="1.12.0" (recording script)
|
||||
root@scripthost:~# ### run commands which
|
||||
root@scripthost:~# ### demonstrate the problem
|
||||
root@scripthost:~# ### a succinct set of commands is best
|
||||
root@scripthost:~# exit
|
||||
logout
|
||||
|
||||
Script saved to script.gz
|
||||
$
|
||||
```
|
||||
|
||||
A `script.gz` like this can be useful to developers to make a repeatable test
|
||||
for the problem. You can attach the `script.gz` file to an issue. Look
|
||||
[here][attach-help] for help with [attaching a file][attach-help].
|
||||
|
||||
# Suggesting a feature or enhancement
|
||||
|
||||
Have an idea for an improvement? Creating a feature request is a good way to
|
||||
communicate it.
|
||||
|
||||
### Before submitting an issue
|
||||
|
||||
Please take a quick look to see whether your idea has been suggested already
|
||||
(there’s a list of [open issues][open-issues]). You can try the search function
|
||||
with some related terms for a cursory check. If you do find a previous feature
|
||||
request, please add a comment there instead of opening a new issue.
|
||||
|
||||
### Submitting a (great) feature request
|
||||
|
||||
Choose the "[Feature request][new-feature]" issue type.
|
||||
|
||||
Summarize your idea with a clear title.
|
||||
|
||||
Describe your suggestion in as much detail as possible.
|
||||
|
||||
Explain alternatives you've considered.
|
||||
|
||||
# Contributing code
|
||||
|
||||
Wow, thank you for considering making a contribution of code!
|
||||
|
||||
### Before you begin
|
||||
|
||||
Please take a quick look to see whether a similar change is already being worked
|
||||
on. A similar pull request may already exist. If the change is related to an
|
||||
issue, look to see if that issue has an assignee.
|
||||
|
||||
Consider reaching out before you start working. It's possible developers may
|
||||
have some ideas and code lying around, and might be able to give you a head
|
||||
start.
|
||||
|
||||
[Creating a hook][hooks-help] is an easy way to begin adding features to an
|
||||
already existing **yadm** operation. If the hook works well, it could be the
|
||||
basis of a **yadm** feature addition. Or it might just be a [useful
|
||||
hook][contrib-hooks] for someone else.
|
||||
|
||||
### Design principles
|
||||
|
||||
**yadm** was created with a few core design principles in mind. Please adhere to
|
||||
these principles when making changes.
|
||||
|
||||
* **Single repository**
|
||||
* **yadm** is designed to maintain dotfiles in a single repository.
|
||||
|
||||
* **Very few dependencies**
|
||||
* **yadm** should be as portable as possible. This is one of the main
|
||||
reasons it has only two dependencies (Bash and Git). Features using other
|
||||
dependencies should gracefully downgrade instead of breaking. For example,
|
||||
encryption requires GnuPG installed, and displays that information if it
|
||||
is not.
|
||||
|
||||
* **Sparse configuration**
|
||||
* **yadm** should require very little configuration, and come with sensible
|
||||
defaults. Changes requiring users to define meta-data for all of their
|
||||
dotfiles will not be accepted.
|
||||
|
||||
* **Maintain dotfiles in place**
|
||||
* The default treatment for tracked data should be to allow it to remain a
|
||||
file, in the location it is normally kept.
|
||||
|
||||
* **Leverage Git**
|
||||
* Stay out of the way and let Git do what it’s good at. Git has a deep and
|
||||
rich set of features for just about every use case. Staying hands off for
|
||||
almost all Git operations will make **yadm** more flexible and
|
||||
future-proof.
|
||||
|
||||
### Repository branches and tags
|
||||
|
||||
* `master`
|
||||
* This branch will always represent the latest release of **yadm**.
|
||||
* `#.#.#` _(tags)_
|
||||
* Every release of **yadm** will have a commit tagged with the version number.
|
||||
* `develop`
|
||||
* This branch should be used for the basis of every change. As changes are
|
||||
accepted, they will be merged into `develop`.
|
||||
* `release/*`
|
||||
* These are ephemeral branches used to prepare new releases.
|
||||
* `hotfix/*`
|
||||
* These are ephemeral branches used to prepare a patch release, which only
|
||||
includes bug fixes.
|
||||
* `gh-pages`
|
||||
* This branch contains the yadm.io website source.
|
||||
* `dev-pages`
|
||||
* This branch should be used for the basis of every website change. As
|
||||
changes are accepted, they will be merged into dev-pages.
|
||||
* `netlify/*`
|
||||
* These branches deploy configurations to Netlify websites. Currently this
|
||||
is only used to drive redirections for
|
||||
[bootstrap.yadm.io](https://bootstrap.yadm.io/).
|
||||
|
||||
### GitHub workflow
|
||||
|
||||
1. Fork the [yadm repository][yadm-repo] on GitHub.
|
||||
|
||||
2. Clone your fork locally.
|
||||
|
||||
```text
|
||||
$ git clone <url-to-your-fork>
|
||||
```
|
||||
|
||||
3. Add the official repository (`upstream`) as a remote repository.
|
||||
|
||||
```text
|
||||
$ git remote add upstream https://github.com/TheLocehiliosan/yadm.git
|
||||
```
|
||||
|
||||
4. Verify you can run the test harness. _(This will require dependencies:
|
||||
`make`, `docker`, and `docker-compose`)_.
|
||||
|
||||
```text
|
||||
$ make test
|
||||
```
|
||||
|
||||
5. Create a feature branch, based off the `develop` branch.
|
||||
|
||||
```text
|
||||
$ git checkout -b <name-of-feature-branch> upstream/develop
|
||||
```
|
||||
|
||||
6. Add changes to your feature branch.
|
||||
|
||||
7. If your changes take a few days, be sure to occasionally pull the latest
|
||||
changes from upstream, to ensure that your local branch is up-to-date.
|
||||
|
||||
```text
|
||||
$ git pull --rebase upstream develop
|
||||
```
|
||||
|
||||
8. When your work is done, push your local branch to your fork.
|
||||
|
||||
```text
|
||||
$ git push origin <name-of-feature-branch>
|
||||
```
|
||||
|
||||
9. [Create a pull request][pr-help] using `develop` as the "base".
|
||||
|
||||
### Code conventions
|
||||
|
||||
When updating the yadm code, please follow these guidelines:
|
||||
|
||||
* ShellCheck
|
||||
* Bash code should pass the scrutiny of [ShellCheck][shellcheck]. The
|
||||
simplest way to quickly test this is to run:
|
||||
* `make test testargs='-k shellcheck'`
|
||||
* Interface changes
|
||||
* Any changes to **yadm**'s interface should include a commit that updates
|
||||
the `yadm.1` man page.
|
||||
|
||||
### Test conventions
|
||||
|
||||
The test system is written in Python 3 using [pytest][pytest]. Tests should be
|
||||
written for all bugs fixed and features added. To make testing portable and
|
||||
uniform, tests should be performed via the [yadm/testbed][testbed] docker image.
|
||||
The `Makefile` has several "make targets" for testing. Running `make` by itself
|
||||
will produce a help page.
|
||||
|
||||
Please follow these guidelines while writing tests:
|
||||
|
||||
* Organization
|
||||
* Tests should be kept in the `test/` directory.
|
||||
* Every test module name should start with `test_`.
|
||||
* Unit tests, which test individual functions should have names that begin
|
||||
with `test_unit_`.
|
||||
* Completely new features should get their own test modules, while updates
|
||||
to existing features should have updated test modules.
|
||||
* Efficiency
|
||||
* Care should be taken to make tests run as efficiently as possible.
|
||||
* Scope large, unchanging, fixtures appropriately so they do not have to be
|
||||
recreated multiple times.
|
||||
* Linting
|
||||
* Python code must pass the scrutiny of [pylint][pylint] and
|
||||
[flake8][flake8]. The simplest way to quickly test this is to run:
|
||||
* `make test testargs='-k pylint\ or\ flake8'`
|
||||
|
||||
### Commit conventions
|
||||
|
||||
When arranging your commits, please adhere to the following conventions.
|
||||
|
||||
* Commit messages
|
||||
* Use the "[Tim Pope][tpope-style]" style of commit messages. Here is a
|
||||
[great guide][commit-style] to writing commit messages.
|
||||
* Atomic commits
|
||||
* Please create only [atomic commits][atomic-commits].
|
||||
* Signed commits
|
||||
* All commits must be [cryptographically signed][signing-commits].
|
||||
|
||||
# Improving documentation
|
||||
|
||||
Wow, thank you for considering making documentation improvements!
|
||||
|
||||
There is overlap between the content of the man page, and the information on the
|
||||
website. Consider reviewing both sets of documentation, and submitting similar
|
||||
changes for both to improve consistency.
|
||||
|
||||
### Man page changes
|
||||
|
||||
The man page documentation is contained in the file `yadm.1`. This file is
|
||||
formatted using [groff man macros][groff-man]. Changes to this file can be
|
||||
tested using "make targets":
|
||||
|
||||
```text
|
||||
$ make man
|
||||
$ make man-wide
|
||||
$ make man-ps
|
||||
```
|
||||
|
||||
While the [markdown version of the man page][yadm-man] is generated from
|
||||
`yadm.1`, please do not include changes to `yadm.md` within any pull request.
|
||||
That file is only updated during software releases.
|
||||
|
||||
### Website changes
|
||||
|
||||
**NOTE:** A [website refactoring][refactor] is being performed soon, and it is
|
||||
unlikely that website changes will be accepted until this task is completed.
|
||||
Better instructions for testing and submitting website changes will be written
|
||||
during that refactor.
|
||||
|
||||
# Maintaining packages
|
||||
|
||||
Maintaining installation packages is very important for making **yadm**
|
||||
accessible to as many people as possible. Thank you for considering contributing
|
||||
in this way. Please consider the following:
|
||||
|
||||
* Watch releases
|
||||
* GitHub allows users to "watch" a project for "releases". Doing so will
|
||||
provide you with notifications when a new version of **yadm** has been
|
||||
released.
|
||||
* Include License
|
||||
* Any package of **yadm** should include the license file from the
|
||||
repository.
|
||||
* Dependencies
|
||||
* Be sure to include dependencies in a manner appropriate to the packaging
|
||||
system being used. **yadm** won't work very well without Git. :)
|
||||
|
||||
# Answering support questions
|
||||
|
||||
Are you an experienced **yadm** user, with an advanced knowledge of Git? Your
|
||||
expertise could be useful to someone else who is starting out or struggling with
|
||||
a problem. Consider reviewing the list of [open support questions][questions] to
|
||||
see if you can help.
|
||||
|
||||
[atomic-commits]: https://www.google.com/search?q=atomic+commits
|
||||
[attach-help]: https://help.github.com/en/articles/file-attachments-on-issues-and-pull-requests
|
||||
[commit-style]: https://chris.beams.io/posts/git-commit/#seven-rules
|
||||
[conduct]: CODE_OF_CONDUCT.md
|
||||
[contrib-hooks]: https://github.com/TheLocehiliosan/yadm/tree/master/contrib/hooks
|
||||
[flake8]: https://pypi.org/project/flake8/
|
||||
[groff-man]: https://www.gnu.org/software/groff/manual/html_node/man.html
|
||||
[hooks-help]: https://github.com/TheLocehiliosan/yadm/blob/master/yadm.md#hooks
|
||||
[new-bug]: https://github.com/TheLocehiliosan/yadm/issues/new?template=BUG_REPORT.md
|
||||
[new-feature]: https://github.com/TheLocehiliosan/yadm/issues/new?template=FEATURE_REQUEST.md
|
||||
[open-issues]: https://github.com/TheLocehiliosan/yadm/issues
|
||||
[pr-help]: https://help.github.com/en/articles/creating-a-pull-request-from-a-fork
|
||||
[pylint]: https://pylint.org/
|
||||
[pytest]: https://pytest.org/
|
||||
[questions]: https://github.com/TheLocehiliosan/yadm/labels/question
|
||||
[refactor]: https://github.com/TheLocehiliosan/yadm/issues/146
|
||||
[shellcheck]: https://www.shellcheck.net
|
||||
[signing-commits]: https://help.github.com/en/articles/signing-commits
|
||||
[testbed]: https://hub.docker.com/r/yadm/testbed
|
||||
[tpope-style]: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
|
||||
[yadm-man]: https://github.com/TheLocehiliosan/yadm/blob/master/yadm.md
|
||||
[yadm-repo]: https://github.com/TheLocehiliosan/yadm
|
||||
Loading…
Reference in a new issue