This workflow page goes through the process of how developers maintain the code driving the website. This consists of a contribution guide, the onboarding documentation, and the development environment setup that developers need to set up their computers to get started with writing code.

This section consists of what DAILP expects in code.

Git GUIs

• DAILP recommends using Sublime Merge.
• If developers use Emacs, magit is the way to go.
• VS Code has basic git support built-in.
• Git CLI works well for the basics: guide.

Git Guidelines

• For Git use feature branches.
• Make atomic commits.
• Developers should avoid git rebase and other history-changing operations.
• Unless developers need to clean up a branch with git rebase --interactive.
• When developers have merge conflicts, use git merge.
• Include both commit message and description when there’s more context around a commit. Use plain git commit for this.

  • This is the commit message.

  • This is the description. The commit message should be a single phrase explanation of the change, while the description can elaborate on how or why the change was made.

    • Use markdown formatting when needed
    • Like lists and emphasis
    • Add hard line breaks at around column 80

  • Example message:

    • "add extra logging to media recorder hook"

Feature Branches

• Use Branching Tutorial for assistance.

1. To work on a task, make a new branch with a related name, e.g. transcription_feature.
2. Once the work is ready for review, create a pull request.
3. Request a code review from two other developers.
4. Follow the steps for deployment.
5. Aim to give code review feedback within 48 hours.
6. Pair to talk through the code in real-time.

The Type

• See more detail on the wiki.

/// A single word in an annotated document.
#[derive(Serialize, Deserialize, async_graphql::SimpleObject)]
#[serde(rename_all = "camelCase")]
#[graphql(complex)]
pub struct AnnotatedForm {
#[serde(rename = "_id")]
pub id: String,
/// Original source text
pub source: String,
/// A normalized version of the word
pub normalized_source: Option<String>,
// More fields below...
}

Serialize The Type

#[derive(Serialize, Deserialize)]

• Automatically generate a serializer at compile-time.
• Allows fast conversion to/from JSON.

#[serde(rename_all = "camelCase")]

• Convert all fields from snake_case to camelCase in JSON.

• Rust object to JSON:

AnnotatedForm {
id: "DF1975:he.walked",
source: "...",
normalized_source: None,
}
{ "id": "DF1975:he.walked",
  "source": "...",
  "normalizedSource": null }

Query The Type

#[derive(async_graphql::SimpleObject)]

• Generate a GraphQL schema entry for this type.
• Generate simple data fields for all struct fields.

#[graphql(complex)]

• Allow computed fields on the GraphQL type.

• GraphQL schema:

type AnnotatedForm {
id: String!
source: String!
normalizedSource: String
}

This contains helpful information about what is needed to get started on coding and setting up a work environment. Start with the checklists below:

General programs checklist

• Have Slack downloaded and set up.
• Have Zoom downloaded and set up.
• Have access to an ideal work environment with macos or Windows.
• Have Nix set up.
• Install direnv.
• Have access to Git.
  • Connect git to ssh.

For Front-end checklist

• Install TypeScript.
• Install vite.
• Install GraphQL.

For Back-end checklist

• Install and get acclimated to Rust.

This is the more specific information that is useful to setting up developers’ DAILP environment on their computers and programs listed in the checklists above.

Nix

• The Nix package manager is a tool DAILP uses for builds and environments.
• Nix:
  • Ensures packages are reproducible environments across systems.
  • Has pinned versions of tooling.
  • Replaces usage of multiple other package managers.

MacOS Setup for Nix

• How to set up MacOS:

1. Run this command in the terminal.
2. Then, run the following commands:

mkdir -p ~/.config/nix
echo "experimental-features = nix-command flakes" > ~/.config/nix/nix.conf

Windows Setup for Nix

• Windows isn’t the best for development.
• Instead, use Linux inside of Windows.

1. Use WSL install guide to help install.
2. Install Nix with this command.

• Potentially relevant advice on Nix on Microsoft Windows.

Linux Setup (non-NixOS)

• How to set up Linux, though we don’t support it or suggests its use with the DAILP API.

1. Follow instructions for multi-user installation.
2. Then, run the following commands:

mkdir -p ~/.config/nix
echo "experimental-features = nix-command flakes" > ~/.config/nix/nix.conf

Install direnv

• DAILP uses direnv because it:

  • Automatically loads development shell.
  • Loads important environment variables from .env.

• Steps:

1. Install the package with Nix:

nix-env -iA nixpkgs.direnv

2. Setup direnv with the shell (by default most systems use BASH).

Clone the project

• Use git to clone the project wherever developers want to:

git clone git@github.com:neu-dsg/dailp-encoding dailp
cd dailp

• Add a file called .env to the cloned repository with these contents:

DAILP_API_URL=http://localhost:8080
GOOGLE_API_KEY=AIzaSyCyhPveBrU9QB4dtOpTbfgnPoktxbEwgcU
DATABASE_URL=postgres://localhost:5432/dailp

• Run this to tell direnv that the developer trusts our environment configuration:

direnv allow

• Note:
  • The first run takes up to ~20 minutes to install.
  • Whenever developers cd to DAILP later, it’ll automatically load Rust, NodeJS, Postgres, etc.

Running everything locally

• Use these commands to run different components locally:
  • dev-database: Database instance.
  • dev-migrate-schema: Run pending schema migrations on local database.
  • dev-migrate-data: Pull data from spreadsheets into local database.
  • dev-graphql: GraphQL server on port 8080.
  • dev-website: Website on port 3001.

Initializing the Database

• Steps:

1. Run dev-database in one terminal, keep that running.
2. In another terminal, run dev-migrate-schema then dev-migrate-data.

• Note:
  • This should take ~15 minutes.
  • Developers only need to run these once.

3. To access the data, run dev-graphql after it finishes.
4. In a third terminal, run dev-website.
5. Open the browser to http://localhost:3001/.

Git

• Git is used for:
  • Version controlling code.
  • Separating feature development from deployed code.
  • Reviewing changes made by other people.
  • Tightly controlling infrastructure changes.
• Connect to git with ssh.
• For specifics information on Git Guidelines and Feature Branches, see Contribution Guide above.