Computational Literacies Lab

Developers

Technical setup

The project you work on will have specific setup instructions, but in general we prioritize a narrow and consistent technical stack:

  • We have a preference for straightforward, well-documented approaches, and open file formats. In research contexts, we like plain-text social science.
  • We use git for version control.
  • Most development is in Python, using uv for dependency management and publishing.
  • We do a small amount of front-end development in Javascript.
  • We use zola to build static websites.

Contributing

We value diverse participation in our research community. We want everyone to feel welcome, valued, and respected. Toward that end, we informally adopt the Contributor Covenant. Your contributions to lab projects, whether paid or unpaid, are licensed under the project license, usually MIT.

Working in branches

Features should be developed in separate branches and merged back into the base branch with a pull request. Good pull requests, whether patches, improvements or new features are a fantastic help and keep our project happy, healthy and wise. They should remain focused in scope and avoid containing unrelated commits.

Here is a summary of the steps to follow:

  1. Before beginning work on a new branch, checkout and update the base branch. The base branch will usually be development unless otherwise agreed upon.
$ git checkout development
$ git pull
  1. Create and checkout the new working branch When creating new branches, refer the branch naming guidelines.
$ git checkout -b <working-branch-name>
  1. During development, you can keep your working branch up to date with ongoing development by fetching from the base branch
$ git fetch origin development
$ git merge origin/development
  1. Follow the commit message guidelines while making your commits.
  2. When your feature is ready for review, open a Pull Request with a clear title and description. The title should give an overview of the feature, change or fix while the description must give elaborated details of the same.
  3. Make sure to mark at least 1 team member as a reviewer on your pull request.
  4. For ambitious tasks, open a Draft Pull Request as soon as possible in order to get continuous feedback and help from the team.

Naming Branches

  1. Use kebab-case while naming your branches. All words must be in lowercase and separated by hyphens. For example, login-api or login-api-fix.
  2. Always make sure that another team member is not working on a similarly named branch before you create a working branch.

Commit Messages

1. Clear & Concise Commits

  • Each commit should correspond to a specific functional change.
  • Ideally a commit should not create an inconsistent state (such as test errors, linting errors, partial fix, etc.)
  • A complex feature should be broken down into multiple commits as long as each one keeps a consistent state and consists of a self-contained change.
  • Avoid using git add . while committing changes, rather add only the relevant files to your commit.
  • Maintain a practice of committing regularly as you cross milestones of your task.
  • Make sure you do not add any build files or secure config files to your commit.
  • If possible, make atomic commits.

2. Commit message format

A good commit message starts with one of the following verbs:

  • Add feature x
  • Remove feature y
  • Update feature z
  • Refactor function x
  • Fix crazy bug
  • Revert previous change

Or any other verb that clearly indicates the type of change being made.

Always use the verbs in Imperative Present tense. Don’t use Past or Present Continuous tenses for commits.

  • Add feature xyz ✔️
  • Added feature xyz ❌
  • Adds feature xyz ❌
  • Adding feature xyz ❌

3. Commit Author

Make sure your name and email ID are configured correctly in your git config so that your commits are authored correctly.

To check if the user name and email is set correctly

$ git config user.name
$ git config user.email

To set a user name or email

$ git config --global user.name "Your Name"
$ git config --global user.email "email@example.com"

omit the --global flag if setting this on a per project basis

4. Tagging Issues

If your commit is related to an existing issue listed on the repo, you can tag it using the issue number. For example, Update otp textbox on login page #23 where 23 is the related issue number.

If your commit completely fixes or resolves an existing issue listed on the repo, you can auto-close it with a reference. For example, Fix #23 otp error on login page. You can also use the keywords "Close" or "Resolve".

You may also link issues manually once you've opened a pull request.

AI policy

Use whatever tools make you most productive. AI is now part of our lives as software developers; let's be open about it and learn together what works. We use a framework developed by Proctor, Bhatt, and Rish (in submission) to think about authorship in collaboration with AI. Authorship can be broken down into three roles:

  • the animator writes the words or the code.
  • the author decides what should be written.
  • the principal is accountable for the writing.

For example, if your friend is sick and you buy a card with a pre-written message inside, hoping they get better soon, you are the principal (you will get credit for sending a nice message, or you'll be held responsible if the card causes offense) but you are not the animator or the author. Another example: when a business executive asks a secretary to write a letter for them, the executive is the principal and the secretary is the animator. They may share the author role.

When you contribute code, you are expected to take on the author and the principal role. That is, you must be prepared to explain in detail what the code is doing, and why this approach is better than alternatives (the author role); you are also responsible for the code, including any harm it may do (creating security vulnerabilities, unintended consequences, or even just wasting reviwers' time).