Skip to main content

Using GitHub with Docassemble

We strongly recommend using GitHub with Docassemble.

GitHub is a version control system. It lets you save a snapshot of your interview that you can revert to an earlier version if you need to and see changes over time. GitHub also makes it easier to build interviews with a team, get help, and hand off your code to future interview builders and maintainers.

Here are some more reasons to use GitHub with Docassemble:

  • Save versions of the interview code you are working on so you can back up to an earlier version/save point if new edits break something.
  • Collaborate with others to build Docassemble interviews, get help, and hand off your code to future interview builders and maintainers.
  • Share your code with others who might want to build similar interviews.
  • Create branches to work on specific issues, or create multiple branches to keep different issues isolated from each other while you work on them.
  • Track and discuss issues with your code, like tasks, bugs, feature requests, etc. Issues can be assigned, tagged, and attached to commits and pull requests that complete or fix them.
  • Use projects to gather issues from multiple repositories and organize them on a Kanban-style project board.
info

This page covers how to use GitHub with Docassemble. Refer to the GitHub documentation if you see unfamiliar vocabulary or have questions about its features.

Workflow​

Here is what we recommend for a workflow for using GitHub with the Docassemble playground. Repeat these steps each time you start working on a new task or issue:

  1. Create a new project in your Docassemble playground. Give it a name that describes the work to be done, then pull the main branch of your interview from GitHub into the project.
  2. When you make your first commit from the new project, commit to a new branch.
  3. When you finish working on the branch, commit it one last time, then go to the repository in GitHub and create a pull request. If you are working with someone on the interview, request a review from them.
  4. Once you have resolved any conflicts and any reviewers have signed off, merge the pull request and delete the branch.
  5. Decide on the next task or issue you want to work on and start over at #1.

We also shared this workflow in a Document Assembly Line workshop:

For more detail on these steps, see below.

How to​

Set up the GitHub integration​

In order to use GitHub with Docassemble you will need two things:

  1. Developer privileges on a Docassemble development server with the GitHub integration configured. (If you don't have access to a Docassemble development server, contact us.)
  2. A GitHub account. If this is a new account, you may want to keep your email address private and avoid sharing your email address on commits.

Once you are set up on GitHub, you can publish your interview package to a GitHub repository.

warning

When publishing your interview package to GitHub for the first time, take a moment to consider the Package Name before you create it. The package name will become part of the GitHub repository name and URL, and it is difficult to change later on.

See our package naming guidelines.

  1. Download your interview package generated by the Weaver, then upload the interview package to a new project in the Docassemble playground.
  2. Follow the Docassemble instructions for publishing an interview package to GitHub. This will create a repository in your personal GitHub account. After you have created the repository, follow these GitHub instructions to transfer it to your organization.
tip

In order to transfer a repository to an organization you must be a member of the organization and have permission to create a repository in the organization.

Create and manage playground projects​

To create and manage projects, in the Docassemble playground click the "Playground" dropdown in the header, then click Manage Projects.

Projects and branches usually have similar names, but project names cannot have underscores, so use PascalCase.

Every time you start working on a new issue, create a new project to work on it. This will help avoid merge conflicts and other problems.

warning

When you pull a GitHub repository to a playground project, the files in the repository will overwrite any files with the same name in your project without warning. You can avoid this by creating a new project instead of pulling a repository to an existing project.

Use issues​

In GitHub, issues are flexible items for planning, discussing, and tracking your work when building interviews. Issues are one of our primary tools for building and maintaining interviews. Discussions on issues can be especially useful for anyone who may work on the interview in the future—including you.

Create an issue for:

  • Tasks
  • Bugs
  • Questions
  • Features
  • Ideas
  • Documentation
  • Etc.

You can also close issues in commit messages and pull request descriptions.

Use branches​

Use branches to isolate the feature, bug, or other issue you are working on. Commit to the branch as you edit, and then when you are finished making your changes, create a pull request to merge the branch into main.

As a general rule, avoid editing the main branch—the default branch. Instead, update main with pull requests from other branches. This creates a cleaner record of changes over time.

It's also best to avoid creating branches from branches other than main—this is a recipe for merge conflicts.

Naming branches​

Name the branch for the issue you are working on. Branch names should be descriptive, unique, and in snake case. One easy way to make the branch name unique is to include the issue or partial date.

For example:

  • 78_update_review_screen (Issue #78 calls for updating the review screen.)
  • 2024_01_update_court_form (Including the year and month makes the branch name more specific.)

Names like these make it easier to tell what issues you (or your teammates) are working on from the list of active branches.

Commit your code​

A commit is a save point. It saves your progress and creates a snapshot of the current state of your interview code. It also helps you find old, working code when something breaks or you need to track down a bug.

GitHub can't help you if you don't use it, so commit early and often!

  1. In the Docassemble playground, click on the Folders menu and select Packages.
  2. Scroll to the bottom of the page and click on the GitHub button.
  3. Select the branch you want to commit to and enter a commit message that describes the change you just made to the interview code.
  4. Do not click the Install package on this server also checkbox.
  5. Click the Commit button.

That's it! Your commit should show up on GitHub! (If you get an error, check these troubleshooting tips.)

tip

When you first start working with Docassemble it can be hard to remember to stop and commit. Try creating a daily reminder on your phone.

You can commit to a branch as often as you want. Developers often wait to commit code until they have it working, but they also might commit broken code so other people can help them troubleshoot, or to save their progress. If you are concerned about ruining working code, make a new branch for the broken code and commit it to that branch.

Commit messages​

Take a moment to consider your commit message. Make it descriptive so you (or someone reviewing your commits) can reconstruct the work you did. This is especially helpful when your interview is broken and you need to find working code from a previous commit.

Here are some example commit messages:

  • Update cash income question
  • Fix broken address field
  • Update e-filing codes
  • Update interview version

Create a pull request​

Refer to the GitHub documentation for how to create a pull request.

Pull request titles should be a summary of the purpose of your changes. They are usually more detailed than the branch name.

Pull request descriptions should provide context, mention related issues, and generally explain the reason for the change.

Here are some good pull request examples:

This helps anyone reviewing your changes—now or in the future.

Resolve conflicts​

Merge conflicts happen to all of us. Refer to the GitHub documentation on resolving merge conflicts.

tip

To reduce merge conflicts:

  1. Keep the goals of your branches "small" so there are fewer changes that can conflict with each other.
  2. Merge pull requests in the order they were made.
  3. Communicate with your team in order to avoid working on the same sections of code at the same time.
  4. Avoid making change that are unrelated to your current goal.

You can also compare commits, branches, etc. in GitHub at any time to see changes more clearly.

Review pull requests​

When someone assigns you to review a pull request (PR), you will be able to see it in your GitHub notifications. Don't let these requests sit around too long, or you increase the likelihood of merge conflicts.

The requester should have left notes on what needs to be tested in the description of the pull request.

  1. Pull the code into the a new playground project.
  2. Test the change(s) made in the pull request.
  3. If it does not do what it is supposed to do, leave a comment asking for changes.
  4. If the new code does what it is supposed to do, approve the changes and then you or the PR submitter can merge the PR and delete the branch.
tip

You can make comments connected to specific lines of code. This is often helpful when reviewing PRs.

Then, delete the playground project you created for the review.

Rename an interview repository​

Changing the name of an interview repository is a multi-step process. For an example, here are the steps to rename docassemble-OldName to docassemble-NewName:

  1. In GitHub, go the repository settings and change the name of the repository in the General settings using the Repository name field.
  2. Clone the repository to your computer (using GitHub Desktop, for example).
  3. In setup.py in the repository's root directory, search and replace "OldName" with "NewName".
  4. Inside the docassemble folder, rename the interview folder from OldName to NewName.

Then you can pull the renamed repository to the Docassemble playground.

Troubleshooting errors when committing from Docassemble​

When you get an error committing from Docassemble, it means Docassemble was unable to change anything on GitHub. One of three things is probably going on.

  1. You have technically not made any changes to the code that is actually being pushed to GitHub.
  2. You lack permissions for the repository you are trying to commit to.
  3. There is a merge conflict to resolve.

Scroll to the bottom of the page to see the details of the error. These are a step-by-step log of what is happening in git, the version-control system GitHub uses. The most recent message is at the bottom. (Ignore the line talking about a Detached head. That is actually a natural intermediate part of the process, not a problem.)

Here are details about the three problems above, how you can identify them, and possible solutions.

If you see nothing to commit, working tree clean​

This means git cannot detect any changes in your code. You cannot commit anything from docassemble if you have not made changes—not even to a new branch. These are some possibilities:

  • If you created a new file you may have not added it to your playground package. Select Folder / Packages and scroll down to the Interview files and Template files sections. Use Command (⌘)+click on a Mac and Ctrl+click on Windows to select the files you want to commit to the repository.
  • You may not have saved changes to a file. If the file is still open you can click the Save button. If the file is closed you will have to open it and make the changes again.
  • You may not actually have made any changes to the files even though you thought you did.

If you see 403​

A 403 error means you do not have write permission for the repository. Ask the person or organization that owns it to give you permission or add you to a team that has permission.

If you are trying to make a new repository on your GitHub account, you may belong to an organization that already has a repository with the same name. You will either have to change the name, have the organization delete its repository, or get permission to write to the existing repository.

If you think your GitHub account does have permission, try redoing the GitHub integration.

If you see CONFLICT (content): Merge conflict​

The text CONFLICT (content): Merge conflict means the branch you are trying to push to changed while you were making your changes. It is what a merge conflict looks like in docassemble in git. Simply make a new branch and commit the changes there. Work out the merge conflicts afterwards.