Add contribution guideline
This commit is contained in:
Tim Byrne
parent
19c6eb6009
commit
f3e4c7d140
|
|
@ -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 New Issue