Thank you for considering contributing to yadm. I develop this project in my limited spare time, so help is very appreciated.
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
- Request features/enhancements
- Contribute changes to code, tests, and documentation
- Maintain installation packages
- Help other users by 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). 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.
If you have found a security vulnerability, do NOT open an issue.
Any security issues should be emailed directly to firstname.lastname@example.org. 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" 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 to the bug
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 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, and use the
scripthost make target. (You will need
$ 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 $
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). 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" issue type.
Summarize your idea with a clear title.
Describe your suggestion in as much detail as possible.
Explain alternatives you've considered.
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 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 for someone else.
yadm was created with a few core design principles in mind. Please adhere to these principles when making changes.
- 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.
- 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.
- 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
- This branch will always represent the latest release of yadm.
- Every release of yadm will have a commit tagged with the version number.
- This branch should be used for the basis of every change. As changes are
accepted, they will be merged into
- This branch should be used for the basis of every change. As changes are accepted, they will be merged into
- These are ephemeral branches used to prepare new releases.
- These are ephemeral branches used to prepare a patch release, which only includes bug fixes.
- This branch contains the yadm.io website source.
- This branch should be used for the basis of every website change. As changes are accepted, they will be merged into dev-pages.
- These branches deploy configurations to Netlify websites. Currently this is only used to drive redirections for bootstrap.yadm.io.
Fork the yadm repository on GitHub.
Clone your fork locally.
$ git clone <url-to-your-fork>
Add the official repository (
upstream) as a remote repository.
$ git remote add upstream https://github.com/TheLocehiliosan/yadm.git
Verify you can run the test harness. (This will require dependencies:
$ make test
Create a feature branch, based off the
$ git checkout -b <name-of-feature-branch> upstream/develop
Add changes to your feature branch.
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.
$ git pull --rebase upstream develop
When your work is done, push your local branch to your fork.
$ git push origin <name-of-feature-branch>
Create a pull request using
developas the "base".
When updating the yadm code, please follow these guidelines:
- Code linting
- Interface changes
- Any changes to yadm's interface should include a commit that updates
- Any changes to yadm's interface should include a commit that updates the
The test system is written in Python 3 using 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 docker image. The
has several "make targets" for testing. Running
make by itself will produce a
Please follow these guidelines while writing tests:
- Tests should be kept in the
- Every test module name should start with
- Unit tests, which test individual functions should have names that begin
- Completely new features should get their own test modules, while updates to existing features should have updated test modules.
- Tests should be kept in the
- 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.
When arranging your commits, please adhere to the following conventions.
- Commit messages
- Atomic commits
- Please create only atomic commits.
- Signed commits
- All commits must be cryptographically signed.
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. Changes to this file can be
tested using "make targets":
$ make man $ make man-wide $ make man-ps
While the markdown version of the man page 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.
The yadm.io website is generated using Jekyll. The bulk of the
documentation is created as an ordered collection within
_docs. To make
website testing easy and portable, use the yadm/jekyll docker image. The
Makefile has several "make targets" for testing. Running
make by itself will
produce a help page.
make test: Perform tests done by continuous integration.
make up: Start a container to locally test the website. The test website will be hosted at http://localhost:4000/
make clean: Remove previously built data any any Jekyll containers.
When making website changes, be sure to adhere to code and
commit conventions. Use the same GitHub
workflow when creating a pull request. However use the
dev-pages branch as a base instead of
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.
- 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 to see if you can help.