uW Developer Guidelines


#1

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:

Other tips for using git:

Licensing

We prefer to license our code with a BSD/MIT style license, when possible. Feel free to copy https://github.com/Door43/tools/blob/master/LICENSE into new projects.

In terms of license assignment and identification, use something very similar to what you see at the top of https://github.com/Door43/tools/blob/master/uwb/t4t2dw.py.

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 https://github.com/unfoldingWord-dev/ and ask around before reinventing the wheel.

Development Workflow

  1. 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.
  2. Write code to implement the feature or fix the bug.
  3. Run all the unit tests. Write more if you discover a new scenario that should be tested.
  4. If you find another bug/problem, write up a separate issue for it. Do not add it to your current task.
  5. 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

  1. Make sure all tests are passing

  2. Review your code changes:

    1. Do not commit any files that have only white-space changes, unless the task was to fix white-space.
    2. Do not make unnecessary white-space changes, it just makes the code review more difficult.
    3. Add appropriate comments to the code to help the reviewers understand why you made the changes and what you are trying to accomplish.
    4. 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.
    5. Remove white-space from the end of lines.
    6. Remove unused includes.
  3. 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
    
  4. Create a pull request from your feature branch into the origin/develop branch, NOT master.

  5. After the code has been reviewed by at least one other developer, address all comments made by the reviewers.

  6. 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.

  7. 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.