Fabio/ddclient
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Start a contributor guide

Browse source 
Addreses #122, #129
This commit is contained in:
Richard Hansen 2020-06-01 12:52:35 -04:00
parent 6e8d7e9744
commit e74797f557
1 changed files with 195 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

195
CONTRIBUTING.md Normal file
View file

@ -0,0 +1,195 @@
# How to Contribute
Thank you for your interest in making ddclient better! This document
provides guidelines to make the contribution process as smooth as
possible.
To contribute changes, please open a pull request against the
[ddclient GitHub project](https://github.com/ddclient/ddclient/pulls).
## Style
* Above all else, try to match the existing style surrounding your
edits.
* No trailing whitespace.
* Use spaces, not tabs.
* Indentation level is 4 spaces.
* Use parentheses for Perl function invocations: `print($fh "foo")`
not `print $fh "foo"`
* When reasonable, break lines longer than 99 characters. Rationale:
- Imposing a limit makes it practical to open many side-by-side
files or terminals without worrying about horizontal scrolling.
- 99 is used instead of 100 so that the +/- column added by
unified diff does not cause wrapping in 100 column wide
terminals.
* Add spaces to vertically align adjacent lines of code when doing
so improves readability.
The following [perltidy](https://metacpan.org/pod/perltidy) command is
not perfect but it can get you close to our preferred style:
```shell
perltidy -l=99 -conv -ci=4 -ola -ce -nbbc -kis -pt=2 -b ddclient
```
## Git Hygiene
* Please keep your pull request commits rebased on top of master.
* Please use `git rebase -i` to make your commits easy to review:
- Put unrelated changes in separate commits
- Squash you fixup commits
* Write your commit message in imperative mood, and explain *why*
the change is made (unless obvious) in addition to *what* is
changed.
If you are not very comfortable with Git, we encourage you to read
[Pro Git](https://git-scm.com/book) by Scott Chacon and Ben Straub
(freely available online).
## Compatibility
We strive to make ddclient usable on a wide variety of platforms.
Please limit yourself to Perl language features and modules available
on the following platforms:
* Debian oldstable and newer
* Ubuntu, [all maintained
releases](https://ubuntu.com/about/release-cycle)
* Fedora, [all maintained
releases](https://fedoraproject.org/wiki/Fedora_Release_Life_Cycle)
* CentOS, [all maintained
releases](https://wiki.centos.org/About/Product)
* Red Hat Enterprise Linux, [all maintained
releases](https://access.redhat.com/support/policy/updates/errata/)
See https://pkgs.org for available modules and versions.
Exception: You may depend on modern language features or modules for
new functionality when no feasible alternative exists, as long as the
new dependency does not break existing functionality on old plaforms.
All shell scripts should conform with [POSIX Issue 7 (2018
edition)](https://pubs.opengroup.org/onlinepubs/9699919799/) or later.
## Prefer Revert and Redo, Not Fix
Suppose a recent change broke something or otherwise needs
refinement. It is tempting to simply push a fix, but it is usually
better to revert the original change then redo it:
* There is less subjectivity with a revert, so you are more likely
to get a quick approval and merge. You can quickly "stop the
bleeding" while you and the project maintainers debate about the
best way to fix the problem with the original commit.
* It is easier and less mistake-prone to cherry-pick a single commit
(the redo commit) than two commits (the original commit plus the
required fix).
* Someone using blame to review the history will see the redo
commit, not the buggy original commit.
## For ddclient Project Maintainers
### Merging Pull Requests
To facilitate reviews and code archaeology, `master` should have a
semi-linear commit history like this:
```
* f4e6e90 sandro.jaeckel@gmail.com 2020-05-31 07:29:51 +0200 (master)
|\ Merge pull request #142 from rhansen/config-line-format
| * 30180ed rhansen@rhansen.org 2020-05-30 13:09:38 -0400
|/ Expand comment documenting config line format
* 01a746c rhansen@rhansen.org 2020-05-30 23:47:54 -0400
|\ Merge pull request #138 from rhansen/dyndns-za-net
| * 08c2b6c rhansen@rhansen.org 2020-05-29 14:44:57 -0400
|/ Replace dydns.za.net with dyndns.za.net
* d65805b rhansen@rhansen.org 2020-05-30 22:30:04 -0400
|\ Merge pull request #140 from ddclient/fix-interpolation
| * babbef1 sandro.jaeckel@gmail.com 2020-05-30 04:03:44 +0200
|/ Fix here doc interpolation
* 6ae69a1 rhansen@rhansen.org 2020-05-30 22:23:57 -0400
|\ Merge pull request #141 from ddclient/show-debug-ssl
| * 096288e sandro.jaeckel@gmail.com 2020-05-30 04:42:27 +0200
| | Expand tabs to spaces in vim
| * 0206262 sandro.jaeckel@gmail.com 2020-05-30 04:40:58 +0200
|/ Show debug connection settings after evaluating use-ssl
...
```
See https://stackoverflow.com/a/15721436 for an explanation of the
benefits.
This semi-linear style is mostly useful for multi-commit pull
requests. For single-commit pull requests, GitHub's "Squash and merge"
and "Rebase and merge" options are fine, though this approach still
has value:
* The merge commit's commit message can link to the pull request
or contain other contextual information.
* It's easier to see who merged the PR (just look at the merge
commit author.)
* You can easily see both the original author timestamp (when the
change was made) and the merge timestamp (when it went live).
To achieve a history like the above, the pull request must be rebased
onto `master` before merging. Unfortunately, GitHub does not have a
one-click way to do this (the "Rebase and merge" option does a
fast-forward merge, which is not what we want). See
[isaacs/github#1143](https://github.com/isaacs/github/issues/1143) and
[isaacs/github#1017](https://github.com/isaacs/github/issues/1017). Until
GitHub adds that feature, it has to be done manually:
```shell
# Set this to the name of the GitHub user or project that owns the
# fork used for the pull request:
PR_USER=
# Set this to the name of the branch in the fork used for the pull
# request:
PR_BRANCH=
# The commands below assume that `origin` refers to the
# ddclient/ddclient repository
git remote set-url origin git@github.com:ddclient/ddclient.git
# Add a remote for the fork used in the PR
git remote add "${PR_USER:?}" git@github.com:"${PR_USER:?}"/ddclient
# Fetch the latest commits for the PR and ddclient master
git remote update -p
# Switch to the pull request branch
git checkout -b "${PR_USER:?}-${PR_BRANCH:?}" "${PR_USER:?}/${PR_BRANCH:?}"
# Rebase the commits (optionally using -i to clean up history) onto
# the current ddclient master branch
git rebase origin/master
# Force update the contributor's fork. This will only work if the
# contributor has checked the "Allow edits by maintainers" box in the
# PR. If not, you will have to manually merge the rebased commits.
git push -f
# If the force push was successful, you can now go into the GitHub UI
# and merge using the "Create a merge request" option.
#
# If the force push failed because the contributor did not check
# "Allow edits by maintainers", or if you prefer to merge manually,
# continue with the next steps.
# Switch to the local master branch
git checkout master
# Make sure the local master branch is up to date
git merge --ff-only origin/master
# Merge in the rebased pull request branch **WITHOUT DOING A
# FAST-FORWARD MERGE**
git merge --no-ff "${PR_USER:?}-${PR_BRANCH:?}"
# Review the commits before pushing
git log --graph --oneline --decorate origin/master..
# Push to ddclient master
git push origin master
```