Docs Contributor Technical Guide

This document explains how to set up your computer and work locally as an ODK Docs contributor. Local set up includes installing some software, and working locally involves:

  • writing documentation text or code in a code editor

  • using the Terminal (the "Shell" or "Command Line")

We encourage all potential contributors to try to work locally, following this guide.

Before you begin

Learn a little about ODK

Read about the project and the community at ODK's website.

Get started with the docs by going to the ODK Docs GitHub README.

Set up collaboration accounts

ODK is a collaborative community. Before diving in as a contributor, set up accounts on our three main collaboration platforms, GitHub, the ODK Developer Slack, and the ODK Forum

Tip

As you are setting up your accounts, keep in mind that it is very helpful (but not required) to use the same (or similar) username on GitHub, the ODK Developer Slack, and the ODK Forum.

This makes it easy for other people to keep track of conversations which sometimes span multiple online platforms.

If you are willing and able to do so, a profile picture in each place is also very helpful. (But it is okay if you are unable or uncomfortable adding a picture.)

  1. Set up a GitHub account.

    GitHub is a popular code storage and collaboration platform. You will need a GitHub account to contribute to ODK documentation, or any other ODK projects.

  2. Join the ODK Developer Slack.

    Slack is a popular chat platform. The ODK contributor community uses Slack to discuss development, plan work, and generally keep in touch. If you have a question about how to contribute to ODK Docs, or any other ODK project, the ODK Slack is the best place to ask it.

    Conversations related to documentation are held in the #docs-code channel. You may also want to check in with #general and #random.

    1. Get an automated invitation from https://slack.getodk.org

    2. Check your email for the invitation.

    3. Follow the link in your email and set up your account.

  3. Join the ODK Forum

    The ODK Forum is the main place for support questions and conversations that affect the whole ODK community (users and other stake holders, as well as contributors).

    If you have a question about how to use any ODK software, or want to get connected with the larger ODK community, the forum is the best venue for that.

    Tip

    The forum has a search feature, and a long history of archived support posts. When writing new documentation about an existing feature, old forum posts are an excellent source for figuring out what people need to know: If someone has asked a question about it, it should probably be in the documentation.

Should I ask in the Forum, the Slack, or a GitHub issue?

The ODK community talks a lot, in a lot of places. Sometimes it's hard to know where to ask a question.

Contribution-related questions and problems should be asked in Slack. This includes things like:

  • How do I set up my local editing environment?

  • How do I use git?

  • I'm having a merge conflict.

  • I got an error at the terminal which I don't understand.

  • How do I add a picture to a document?

  • What issue should I work on?

Work-specific questions and discussion should take place on the GitHub issue defining the work. This includes things like:

  • I'm writing a piece of content, but I'm not sure where it should be organized.

  • I'd like to work on this feature, but I don't know how to implement it.

  • Here's my idea for solving this problem. Is that a good idea?

  • I'm going to be working on this for the next few days. No one else should also work on it at the same time.

  • I said I was working on this, but I didn't finish and I'm no longer working on it.

User-related questions and problems should be asked in the Forum. (You should use the search feature first, since someone else may have already asked the same question.) This includes things like:

  • How do I install an ODK application?

  • How do I create a form?

  • How do I add a specific feature to a form?

  • My ODK application crashed.

But don't worry about posting a question in the wrong place.

It is better to ask a question in the "wrong" venue than to not ask the question at all. Many of the same people are present in all three places, and we will help you wherever you happen to show up.

Initial Setup

Note

We generally recommend starting with the Docker platform for editing docs unless you already have a Sphinx environment set up. Local tools and workflows presented in this guide are what the authors feel would be easiest for newcomers and those unfamiliar with open source.

However, developer and authoring tools have a lot of options and alternatives. You should feel free to use your preferred tools.

Before you begin working the first time you will need to install a few tools on your computer.

You should only need to do this one time on any computer.

  1. Find and open a terminal or command line.

    Windows versions prior to Windows 10

    Use Windows PowerShell. (Not the DOS Prompt.)

    We recommend using the Windows PowerShell ISE.

    During initial setup (this section of the guide) you will need to Run as Administrator.

    Throughout the rest of the instructions in this guide, follow the instructions labeled PowerShell or Windows.

    Windows 10

    In Windows 10, you have a choice:

    If you decide to use the Powershell, follow the Powershell or Windows instructions throughout the contributor guides.

    If you decide to use the Linux subsystem, follow the Bash or Windows instructions throughout the contributor guide.

    Note

    Computers with the Windows 10 Home operating system are incapable of installing some of the tools necessary to edit the docs. Other Windows operating systems, such as Windows 10 Enterprise or Pro, can be used to edit the docs.

    Use the Terminal app, or another Bash-like shell.

    The Terminal Icon in Mac OS.

    If you've never used it before, the Terminal is probably in the Other directory in your App collection.

    Follow the Bash or Mac instructions throughout the contributor guide.

    Optional: Install Homebrew

    Homebrew is a package manager for Mac OS. It makes it easier to install other apps and tools from the command line.

    Follow the installation instructions.

    Use a Bash-like shell of your choosing, and follow the Bash or Linux instructions throughout the contributor guide.

    You will also need to be familiar with the relevant package manager for your system.

  2. Install git.

    Git is a version control system. It helps us keep track of changes to the documentation. (Similar to the undo history in a document editing program.)

    Use your distribution's package management system to install git on Linux.

    Option 1: Download an installer

    1. Download the git installer for Mac.

    2. Open the installer package.

    3. Follow the prompts.

    4. Accept any default settings.

    Option 2: Use Homebrew to install git

    $ brew install git

    1. Download the git installer for Windows.

    2. Open the installer package.

    3. Follow the prompts.

    4. Accept any default settings.

  3. Install Git LFS

    Git Large File Storage (Git LFS) is a tool that helps us manage images, videos, and other files which are neither text nor code.

    Use your distribution's package management system to install Git LFS on Linux.

    After initial installation by the package manager, complete the install by running:

    $ git lfs install

    1. Download Git LFS from the Git LFS website.

    2. Open the downloaded installer.

    3. Follow the prompts.

    4. Accept any default settings.

    5. Open the Terminal and add LFS to git:

      $ git lfs install

    Option 2: Use Homebrew to install Git LFS.

    $ brew install git-lfs
$ git lfs install

    1. Download Git LFS from the Git LFS website.

    2. Open the downloaded installer.

    3. Follow the prompts.

    4. Accept any default settings.

    5. Open Powershell and add LFS to git:

      > git lfs install

  4. Install Python 3

    Python is a programming language.

    Most of the ODK Docs tools are written in Python, so you need it installed on your computer in order to use those tools. (Don't worry. You don't need to know how to program in Python.)

    We require Python 3, version 3.6 or later.

    Use your distribution's package management system to install Python 3.6+ on Linux.

    (For more help, see Installing Python on Linux.)

    Tip

    Mac OS includes a legacy (outdated) version of Python. It's best to just ignore it.

    Option 1: Use the Python Installer for Mac

    1. Download the latest Python installer for Mac.

      64-bit or 32-bit?

      Python provides 64-bit and 32-bit installers. You probably need the 64-bit installer.

      If you are running a relatively recent Mac OS update (Mountain Lion or later — any Mac from the last several years) the 64-bit installer is for you.

      If you have an older Mac, and are unsure if it can run a 64-bit installer, check the processor details in  -> About This Mac.

    2. Open the Installer.

    3. Follow the prompts.

    4. Accept the default settings.

    5. Open the Terminal to see if Python installed properly.

      $ python3 --version
Python 3.7.0

      The output from python3 --version might be a little different, but it should be higher than 3.6.

      If you get an error here, something went wrong. Try running the installer again.

    Option 2: Use Homebrew to install Python 3.6+

    $ brew install python
.
.
.
$ python3 --version
Python 3.7.0

    The output from python3 --version might be a little different, but it should be higher than 3.6.

    If you get an error here, something went wrong. Try running brew install python again.

    1. Go to the Python Releases for Windows page.

    2. Under the latest numbered release for Python 3, find and download the Windows x86-64 web-based installer (for a 64-bit system) or the Windows x86 web-based installer (for a 32-bit system).

      64-bit or 32-bit?

      Well over 90% of computers running Windows are 64-bit. So you probably need the 64-bit version.

      If you are running a very old or low-powered computer, and you are unsure if it is 64-bit or 32-bit, you can use this guide from HP (which will work for other computer brands) to find that information.

    3. Open the downloaded installer.

    4. Follow the prompts.

    5. Accept all default settings.

    6. Open Powershell and make sure the installation completed.

      > python --version
Python 3.7.0

      The output from python --version might be a little different, but it should be whatever numbered version you downloaded.

      If you get an error here, something went wrong. Try running the installer again. You may also have to add Python to your Windows search path. You can do this by going to Advanced System Settings -> Environmental Variables -> Edit System Variables, then adding the path to the directory containing Python.

  5. Set up your working directory

    In whatever directory (folder) on your computer where you organize projects, create a new directory for ODK, and then navigate to that directory. (We recommend calling this directory odk, and the rest of the guide will assume that's what you called it.)

    $ mkdir odk
$ cd odk
/odk/ $

    > mkdir odk
> cd odk
/odk/ >

    For the rest of this guide, we assume you are in the /odk/ directory, or a subdirectory of it.

  6. Set up a virtual environment

    A virtual environment is a Python construct that lets you download and install tools for a specific project without installing them for your entire computer.

    1. Create the virtual environment.

      /odk/ $ python3 -m venv odkenv

      /odk/ > python -m venv odkenv

    2. Activate the virtual environment.

      /odk/ $ source odkenv/bin/activate
(odkenv) /odk/ $

      /odk/ > source odkenv/bin/activate
(odkenv) /odk/ >

      The (odkenv) before the prompt shows that the virtual environment is active. You will need to have this active any time you are working on the docs.

      If the file cannot be found, your activate file may be located under odkenv/scripts/activate.

      Later, to deactivate the virtual environment:

      (odkenv) /odk/ $ deactivate
/odk/ $

      (odkenv) /odk/ > deactivate
/odk/ >

  7. Fork the ODK Docs repository to your own GitHub account.

    A repository (repo) is a store of all the code and text for a project. The ODK Docs repo is kept at GitHub.

    On GitHub, a fork is a copy of a repo, cloned from one user to another. In order to work on ODK Docs, you will create your own fork.

    1. Go to the ODK Docs repo on GitHub.

    2. Use the Fork button (top right) to create your own copy.

    3. After the process completes, you'll be looking at your own fork on GitHub.

  8. Clone down your copy to your local computer

    1. From your own fork of the repo on GitHub, select the Clone or download button.

    2. Copy the URI from the text box that opens. It will be something like: https://github.com/your-gh-username/docs.git

    3. Use your terminal to clone the repository.

      You should already be in the odk directory, with the virtual environment active.

      Note

      This will cause your computer to download the entire ODK Docs repository, including a large number of images. It will take several minutes to complete.

      (odkenv) /odk/ $ git clone https://github.com/your-github-username/docs.git
.
.
.
(odkenv) /odk/ $ cd docs
(odkenv) /odk/docs/ $

      (odkenv) /odk/ > git clone https://github.com/your-github-username/docs.git
.
.
.
(odkenv) /odk/ > cd docs
(odkenv) /odk/docs/ >

      Warning

      Some of the git commands produce meaningless errors in PowerShell. If you get an error when using git, but everything seems to work otherwise, ignore the error.

      Your local directory

      If you followed the instructions, you should now have the following directory structure:

      • odk

        • docs

        • odkenv

      The odkenv directory stores your virtual environment, and you should not need to open it or directly view its content. Just ignore it.

      The docs directory is your copy of the ODK Docs repo. You will do most of your work in this directory.

      If you need to download or create additional files which are not actually a part of the ODK Docs repository, keep them out of the docs directory.

      You can use the main odk directory for any other files you need to work on. (For example, you may want to create a directory called odk/forms to hold XLSForm and XForm files.)

  9. Set the upstream remote

    In git, a remote is a copy of a repo somewhere else. From your local computer's point of view, your online copy at GitHub is a remote.

    When you cloned down a repo, your local copy gives your GitHub copy the name origin.

    You also need to give the primary ODK Docs repo a name, and our convention is to name it upstream.

    (odkenv) /odk/docs/ $ git remote add upstream https://github.com/getodk/docs.git
(odkenv) /odk/docs/ $ git remote -v
origin https://github.com/your-github-username/docs.git (fetch)
origin https://github.com/your-github-username/docs.git (push)
upstream https://github.com/getodk/docs.git (fetch)
upstream https://github.com/getodk/docs.git (push)

    (odkenv) /odk/docs/ > git remote add upstream https://github.com/getodk/docs.git
(odkenv) /odk/docs/ > git remote -v
origin https://github.com/your-github-username/docs.git (fetch)
origin https://github.com/your-github-username/docs.git (push)
upstream https://github.com/getodk/docs.git (fetch)
upstream https://github.com/getodk/docs.git (push)

    If everything went right, you should see output similar to what is shown above.

  10. Install Python tools with pip

    Pip is a package management tool that comes with Python. We use it to download and install our documentation tools. These Python tools are listed in requirements.txt.

    (odkenv) /odk/docs/ $ pip install --upgrade pip
(odkenv) /odk/docs/ $ pip install -r requirements.txt

    (odkenv) /odk/docs/ > pip install --upgrade pip
(odkenv) /odk/docs/ > pip install -r requirements.txt

    The first command upgrades pip itself to the latest version. Then second checks requirements.txt and installs everything listed in it. This will take several moments.

    Note

    If you are ever running one of the build commands shown below and it fails with a message that includes ModuleNotFoundError, there might be changes to requirements.txt since you originally ran pip install -r requirement.txt. Run the installation again and then retry your build.

  11. Choose a text/code editor

    The documentation source files are written in a plain text format called reStructuredText. This means special formatting (bullets, headers, bold text) is represented by visible characters, not hidden behind a graphical display. When working on a documentation file, you see and write something that looks like:

    #. Choose a text/code editor

   The documentation source files
   are written in a plain text format called `reStructuredText`_.

   .. _reStructuredText: http://docutils.sourceforge.net/docs/user/rst/quickref.html

    You cannot write and edit these files in a typical document preparation program like MS Word or Google Docs. Instead, you need a coding editor.

    There are a lot of editors, and people who use them often have very strong opinions about them. You are free to choose any editor you like.

    If you've never used an editor before, you might want to start with one of the easier and more popular ones:

    Most of these have plugins that will make writing reStructuredText easier by color-coding the markup.

This completes the setup of your local working environment. Take a break before diving into how you actually work.

Working on the docs

  1. Find an issue to work on.

    Work on ODK Docs is planned using the GitHub repository's issue tracker.

    1. Browse the issue tracker and find one you may want to work on.

    2. Make sure you understand the goal of the project. If the goal isn't clear, ask. If there is anything in the issue that doesn't make sense, ask about it. Feel free to make suggestions about how something could be accomplished.

    3. If you decide to work on an issue, assign yourself to it by writing @getodk-bot claim in a comment.

    4. If the issue requires a novel or creative solution not defined in the issue already (we've stated a problem and you think you know a way to fix it) write a comment describing your plan. It is a good idea to get feedback on an idea before working on it. Often, other contributors can provide additional context about why a particular solution may or may not work.

    Your first issue

    The very first issue you should work on as a new ODK Docs contributor is Issue 96 — Line Edits. The issue is very simple:

    1. Find a typo.

    2. Fix the typo.

    This will help you get used to working with the documentation tools, and helps us get rid of the inevitable errors that creep in to our writing.

  2. Make sure you are on the master branch

    A branch is a named sequence of changes representing work on the repo. For example, if you were going to work on Issue 96 — Line Edits, you would create a new branch called line-edits to hold that work. When you were done, you would merge those changes back to the main branch, which we call master.

    The first time you clone the docs repo and start working, you will be on the master branch.

    Each time you come back to starting work on a new issue, make sure you are on the master branch before continuing.

    1. Check the current branch with git branch. This will output a list of branches, with a star next to the current one.

      (odkenv) /odk/docs/ $ git branch
   branch-name
   branch-name
   branch-name
 * master
   branch-name

      (odkenv) /odk/docs/ > git branch
   branch-name
   branch-name
   branch-name
 * master
   branch-name

    2. If you are not on master, switch to master with git checkout.

      (odkenv) /odk/docs/ $  git checkout master
Switched to branch 'master'
Your branch is up to date with 'origin/master'.

      (odkenv) /odk/docs/ >  git checkout master
Switched to branch 'master'
Your branch is up to date with 'origin/master'.

  3. Pull in changes from upstream

    Other people are constantly making changes to the docs, so you need to keep your local copy up to date.

    Before you start working, use git pull to pull in the changes from the upstream repository's master branch. Then, just to be sure, you can use git status to make sure everything is up to date.

    (odkenv) /odk/docs/ $ git pull upstream master
(odkenv) /odk/docs/ $ git status
On branch master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean

    (odkenv) /odk/docs/ > git pull upstream master
(odkenv) /odk/docs/ > git status
On branch master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean

    Warning

    Some git commands (including git pull and git checkout) send error messages to PowerShell even when they work correctly. If everything seems to be working, you can ignore these.

  4. Create a new branch for your work.

    (odkenv) /odk/docs/ $ git checkout -b branch-name
Switched to a new branch 'branch-name'

    (odkenv) /odk/docs/ > git checkout -b branch-name
Switched to a new branch 'branch-name'

    Branch names should be short, lowercase, and use hyphens as separators. They do not need to carry a lot of information (like your name or the date).

    Good branch names:

    • getting-started-guide

    • contributing

    • fix-issue-13

    Bad branch names:

    • getting started guide

    • Getting started guide

    • Getting_started_guide

    • writing-the-getting-started-guide-adammichaelwood-july-2017-draft

  5. Work on the documentation

    Finally, you can open an editor of your choice and work on the documentation.

    The source files for documentation text are in these directories:

    src

    Files for the pages at https://docs.getodk.org

    If you're going to write or edit documentation text, please read:

    If you're working on code or deployment, please read:

  6. Local checks

    Once you have worked on the documentation, we want to make sure your contribution will get accepted and published right away.

    To ensure your changes will pass all the deployment tests, you should run the tests locally first and correct any problems.

    1. Spell check

      If you've been working on files in src:

      (odkenv) /odk/docs/ $ make spell-check

      (odkenv) /odk/docs/ > rm -r -fo tmp
(odkenv) /odk/docs/ > rm -r -fo build
(odkenv) /odk/docs/ > Copy-Item src -Destination tmp -Recurse
(odkenv) /odk/docs/ > sphinx-build -b spelling tmp build/spelling
(odkenv) /odk/docs/ > python util/check-spelling-output.py build

      This will send some output to the terminal, which will include mentions of any words not in the dictionary.

      • If the flagged words are really misspellings, correct them.

      • If the flagged words are not misspelled, and should be in the dictionary add them to spelling_wordlist.txt.

      • If the flagged words are not misspelled, but should not be in the dictionary (for example, they are non-words that make sense on a single page for a specific reason) add them at the top of the file in which they are being used, before the title heading:

        .. spelling:word-list::

   abc
   def
   exe
   functool

This Is The Page Title
======================

      When adding new words to spelling_wordlist.txt or the top of a document file, please keep the words in alphabetical order.

    2. Style check

  7. Build and check

    We use a Python tool called Sphinx to compile all the .rst files into a working website.

    If you've been working on files in src:

    (odkenv) /odk/docs/ $ make build

    (odkenv) /odk/docs/ > rm -r -fo tmp
(odkenv) /odk/docs/ > rm -r -fo build
(odkenv) /odk/docs/ > Copy-Item src -Destination tmp -Recurse
(odkenv) /odk/docs/ > sphinx-build -b dirhtml tmp build

    This generates a lot of output. Near the end of the output you may see a statement like:

    build succeeded, 18 warnings.

    Those warnings are problems with the text which you need to fix before submitting your changes. Scroll up in the terminal to find each warning, so that you can address it in the source files.

    A Sphinx warning looks like this:

    /path/to/file-name.rst:LINENUMBER: WARNING: warning message

short excerpt from the file

    This tells you what file the problem is in, the approximate line number, and the nature of the problem. Usually that is enough to fix it.

    Note

    Because of a bug in Sphinx the line numbers in error and warning messages will be off by about 15 lines (the length of rst_prolog in conf.py).

    As you fix each warning, run the build again to see if it disappears from the output.

    Note

    The warning messages will refer to the file name using the temporary directory path tmp. You need to correct the problems in the real source directory (src).

    When you just can't fix the error…

    If you've done your best and you still cannot correct the warning, stop worrying about it and skip to the next step. When you submit your changes on GitHub, include a note about the warning. Other contributors will help solve the problem before merging.

    Once you've corrected all the warnings that can be corrected…

  8. Serve the documentation website locally and view it.

    If you've been working on files in src:

    (odkenv) /odk/docs/ $ python -m http.server -d odk-build 8000
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/)

    (odkenv) /odk/docs/ > python -m http.server -d build 8000
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/)

    1. Open your browser and go to http://localhost:8000.

    2. Read through your doc edits in the browser.

    3. Go back to the source files to correct any errors you find.

    4. Go to your terminal, and press CTRL C to shut down the local web server.

    5. Re-run the build and serve steps.

    6. Continue proofreading.

    Once you are reasonably sure your changes are ready…

  9. Commit your changes to your local repository.

    A commit is snapshot of your working files in a particular state, along with a record of all the changes that led up to that state. That snapshot is what you will submit to the main repository.

    Note

    We explain how to do a commit at this step because you need to do it before you can submit your changes. However, you don't have to wait until you are done to commit. You can commit as many times as you like while working.

    This can be especially helpful if you are working on a complicated set of changes, over several working sessions.

    1. Stage the files for commit with git add.

      To stage all changes for commit:

      (odkenv) /odk/docs/ $ git add -A

      (odkenv) /odk/docs/ > git add -A

    2. Commit the staged files with git commit.

      (odkenv) /odk/docs/ $ git commit -m "Write a commit message here."

      (odkenv) /odk/docs/ > git commit -m "Write a commit message here."

      Your commit message needs to be wrapped in quote marks. It should, in a sentence or less, explain your work.

  10. Push your committed changes to your GitHub repo with git push.

    Tip

    You may be prompted to enter your GitHub username and password. When entering your password, the cursor won't move — it will look like you aren't entering anything, even though you are.

    To avoid having to retype these every time, you can store your GitHub credentials locally.

    (odkenv) /odk/docs/ $ git push origin branch-name

    (odkenv) /odk/docs/ > git push origin branch-name

    Warning

    The git push command produces meaningless errors in PowerShell. If you get an error when using git push, but everything seems to work otherwise, ignore the error.

  11. Issue a pull request from your GitHub repo to the main ODK Docs repo.

    A pull request (or PR) is a request from you to the ODK Docs maintainers to pull in your changes to the main repo.

    1. Go to the ODK Docs repo on GitHub. (Make sure you are logged in.)

    2. Find the message near the top of the page that mentions your recent pushed branches. Select Compare & pull request to start a pull request.

    3. Follow GitHub's instructions to start the pull request.

      These details should fill-in automatically, but be sure to double-check them:

      • Base fork should be the main repo (getodk/docs).

      • base should be master.

      • Your repo and working branch name should be listed beside them.

      You will see either a green Able to be merged message or a message informing that the branch can not be merged. You can proceed in either case. If the branch cannot be merged, the maintainers will work with you to resolve the problem.

    4. Write a PR message explaining your work.

      The PR message field includes a template to remind you of what to include. Fill in the template and delete any sections which are not applicable.

      A good PR message includes:

      • The issue number you are working on. (Write closes #123 if the PR completes the work for the issue. If there's still work to do, write addresses #123.)

      • A summary of what you did.

      • Details of work that still needs to be done.

      • Details of new work created or implied by this PR.

      • Details of any unresolved errors or warnings, including details of what you tried.

      • Justification for any changes to requirements.txt.

      • Details of any difficulties, questions, or concerns that came up while working on this issue.

    5. Submit your pull request.

    The maintainers and other contributors will review your PR as quickly as possible. They may request changes to your work. If changes are needed:

    1. Don't worry. Revision is a normal part of technical writing, and everyone (even the project's founders and leaders) has their work reviewed and are frequently asked to revise it.

    2. Work on the files again locally. (Use git branch to make sure you are still in the same working branch.)

    3. Stage and commit your changes locally again (git add -A; git commit -m "Commit message").

    4. Push your commit (git push origin branch-name).

    5. Your new commits will automatically update the PR. Do not start a new PR.

    Once everything has been approved, the changes will be merged in and will appear on this website. At that point… congratulations! You are now a contributor to ODK.

The next time you work

We hope that contributing to ODK Docs is a rewarding experience and that you'll want to keep going. Each time you start work on a new issue the process is the same as outline above.

Here are a few things to keep in mind when you start your next contribution.

  1. Return to master with git checkout master.

    New work is done on new branches which are started from master. So, before you start a new branch, return to the master branch.

    (odkenv) /odk/docs/ $ git checkout master

    (odkenv) /odk/docs/ > git checkout master

  2. Pull in changes with git pull upstream master.

    You need to start your new work from the latest version of everyone else's work.

    (odkenv) /odk/docs/ $ git pull upstream master

    (odkenv) /odk/docs/ > git pull upstream master

  3. Update the master branch of your online GitHub repository.

    (odkenv) /odk/docs/ $ git push origin master

    (odkenv) /odk/docs/ > git push origin master

  4. Find a new issue to work on.

  5. Start a new branch for your work with git checkout -b branch-name.

Keep improving

As you are getting comfortable with the contribution process, take a few minutes to read our Tips for Making Good Contributions. You may also want to dig deeper into the Docs Style Guide and the Docs Markup and Syntax Guide. (And if you are writing code, check out the Docs Developer Guide.)

ODK is a community, and we depend on each other's work. Thank you for your contribution to ODK Docs and your presence in this community.

Did this page help you?

Selecting an option will open a 1-question survey

👍 Yes 👎 No