Goal
Create useful code to further unrestricted biblical content in every language.
Ideals
In order to create useful code, we adopt these time and scale proven ideals.
Do One Thing Well
Every package should do one thing well. If a contrariwise feature is needed, turn it into its own package.
API Driven
Every package must provide an API. Expect to receive input from other packages and to provide output to other packages.
Stateless
Every package must be stateless. Persistent data must be stored in external packages designed explicitly for it.
Minimum Viable Product
Every package should deliver the minimum viable product, anything more is wasteful.
Small Wins
Every package and every change should be as small as possible.
Explicit Dependencies
Every package must explicitly reference the versions of the packages it depends on.
Automated Testing
Every package must employ a combination of automated unit and acceptance testing.
Continuous Deployment
Every package must be configured for continuous deployment given passing automated tests.
Guidelines
The following is not an exhaustive list but just a few pointers to keep us on the same page.
Source Code Management
We use git for managing code (lots of content, too) and usually Github. This makes everyone’s life easier. If you need help here, see these helpful sites:
- https://help.github.com/ and Set up Git - GitHub Docs.
- See also the Git manual: Git - Documentation
- Tutorial for learning git branching: Learn Git Branching
Other tips for using git:
- Commit often and use helpful messages, see good advice at My favourite Git commit | dhwthompson.com.
- Configure your git client to
autocrlf. Instructions can be found here. All files should be pushed to Github with Unix line endings (LF, notCRLF). - Most of our projects also use “git-flow” as described in A successful Git branching model » nvie.com.
Licensing
We prefer to license our code with a BSD/MIT style license, when possible. Feel free to copy tools/LICENSE at master · unfoldingWord-dev/tools · GitHub into new projects.
In terms of license assignment and identification, use something very similar to what you see at the top of tools/t4t2dw.py at master · unfoldingWord-dev/tools · GitHub.
Following the above practices will ensure that the copyright holder is clearly identified as unfoldingWord but also that individual developers are attributed appropriately for the portions of code that they worked on. Of course, being able to see who wrote the code by looking at the top of the file is helpful if you have a question.
Don’t Duplicate
Use existing code whenever possible. If someone has already done what you are trying to do, or even something slightly similar, see if you can use that first (of course check the license). Also, make sure to check in unfoldingWord-dev · GitHub and ask around before reinventing the wheel.
Development Workflow
- Write at least one unit test that fails, but that would pass if you had already completed the task. For a new feature this will verify your code implements all the requirements for the feature. If the task is a bug fix, make sure the tests fail for the right reason (because of the bug) and when you have finished the task they will prove you actually fixed the bug.
- Write code to implement the feature or fix the bug.
- Run all the unit tests. Write more if you discover a new scenario that should be tested.
- If you find another bug/problem, write up a separate issue for it. Do not add it to your current task.
- If tests that were passing before you started the task are now failing, figure out why and fix them. If a test is now wrong because of the changes you made, fix the test. If you broke something in the code, fix it. All tests must be passing locally before you submit a pull request.
Before Submitting a Pull Request
-
Make sure all tests are passing
-
Review your code changes:
- Do not commit any files that have only white-space changes, unless the task was to fix white-space.
- Do not make unnecessary white-space changes, it just makes the code review more difficult.
- Add appropriate comments to the code to help the reviewers understand why you made the changes and what you are trying to accomplish.
- Make sure white-space is consistent, do not mix tabs and spaces in the same file. All new development will use spaces to indent. The only time it is acceptable to use tabs if when modifying a legacy file that already uses tabs.
- Remove white-space from the end of lines.
- Remove unused includes.
-
Commit your changes. The first line of the commit message will become the title of the pull request. It should contain a short description and needs to be less than 50 characters. Following that, leave one blank line and then include a more detailed description, including a link to the Github issue. This is an example:
Fix 404 error on door43.org home page There is a 404 error being displayed when anyone navigates to the door43.org home page. Issue unfoldingword-dev/door43.org#134 -
Create a pull request from your feature branch into the origin/develop branch, NOT master.
-
After the code has been reviewed by at least one other developer, address all comments made by the reviewers.
-
When all reviewers give the “thumbs up” and you are satisfied, merge your pull request or ask someone else to merge it if you don’t have permission.
-
Delete the feature branch so it doesn’t become messy and confusing.
Servers
For those that need it, access to our servers is allowed only via SSH public key authentication to non-root accounts. If you are on Windows, you may need PuTTY. If you are creating a new key, use these options, ssh-keygen -t rsa -b 4096.