Development Processes

We want to be organized as a team and maintain high communication, visibility, and review in our work. We draw from some values of Agile, Scrum, and common practice in Human-Computer Interaction research.

Development Process

Writing Code

• Always run the relevant code formatter on your changes before committing them. TypeScript = prettier, Rust = rustfmt/cargo fmt, SQL = sqlfluff

Design

1. 📌 Define your broad goal with a paragraph including:
   • What is your solution?
   • Who is it for?
   • How does it compare to existing solutions?
2. 📝 Elaborate your ideas as a functional specification, which includes non-functional requirements, user stories, user personas, functional requirements, and any other details that help you define the specifics of the problem and solution. This document becomes the source of perspective that you should frequently refer to, asking questions like: Am I meeting the needs of all relevant users?
3. 🎨 Draft a prototype, ideally on paper, which focuses on experience and layout while ignoring aesthetics and graphic design. It's easier to suspend disbelief on paper, but primitive greyscale digital drawings work too.
4. ♻️ Continuously evaluate your designs according to common design heuristics, for example Nielsen's heuristics.
5. 🚧 Conduct usability evaluations where users in your target audience click/tap/navigate through your experience, talking through what they are doing. Conducting these evaluations effectively and ethically is a separate topic of discussion. Evaluate your designs with users early and often. You will never be completely confident in your design, especially without external feedback, so don't be afraid to share designs that you know have issues.
6. ♻️ Repeat steps 3 through 5, iterating on your design in increasingly higher fidelity: paper drawings -> digital greyscale drawings -> interactive prototype built with static images (e.g. PowerPoint) -> actual implementation.
7. 📝 Document the changes made from each iteration to the next with justification and reference to some stage of evaluation or review.
8. 🎉 Once pieces of the design are solidified by sticking around for several iterations, those pieces are handed off for implementation. Ideally, continue to iterate on the design alongside implementation.

Implementation

1. 🔀 Each feature, bug fix, or change is built on a feature branch starting at main.
2. 🎁 When the changes are ready for review, make a Pull Request into the main branch.
3. ✔️ Several checks will run to confirm that the branch hasn't broken everything, and a front-end preview of the branch will be deployed.
4. 🎉 Once the PR has been reviewed and approved, merge it with a merge commit into main
5. 🚀 Each merge into main will deploy all infrastructure and code changes to https://dev.dailp.northeastern.edu
6. ⬆️ Once the code in main is ready for production, make a GitHub release. Choose a version of this format v1.0.0 following Semantic Versioning that increments on the previous release version. In the description, outline major changes since the last release.
7. 🚀 Once the release is published, the development deployment will be promoted to production at https://dailp.northeastern.edu.

Monthly Project Planning

Disclaimer: This is an ideal and not exactly what we do right now.

Project planning meetings should be about once a month.

1. 📌 Identify goals and stakeholders for each major goal
2. 📝 Describe each goal with a broad paragraph
3. ⚙️ Collect a rough estimate of effort from every team member that will be involved in achieving this goal
4. 📆 If possible, define either an ideal deadline or total number of weeks based on an aggregate of the team estimates
5. ⛏️ For the current goal to work on, meet as a team to outline more granular tasks to meet the goal. These may still be pretty broad to be broken down later. Each task should be associated with one or more specific goals, such that when all tasks associated with a goal are complete, then the goal is considered achieved.

Weekly Meeting

Disclaimer: This is an ideal and not exactly what we do right now. We could follow this process at every team meeting to keep all tasks up to date.

Work Done

This process is an enhancement of our current practice of giving updates from a rolling agenda. Here, each update must have an associated task tracked for the whole team to see its progress.

1. 📋 View the current project board
2. ⬆️ Go through each task that's newly done, in review, or in progress. For each one, the assigned team member should give an update on where they're at with it.
3. 📎 If a task needs a reviewer, assign one now.
4. ⛏️ If a task hasn't changed status in the past week, consider breaking it into multiple smaller tasks.
5. 🎉 Make final changes to the status of the past week's tasks.

Planning

This process augments the end of our team meetings where we discuss what's next. Ideally, everything that anyone is working on is explicitly tracked for us all to see.

1. 📋 View the backlog of tasks associated with the currently in-progress goals.
2. ✨ Ask every team member what they'd like to work on this week, pulling those tasks into UP NEXT. Aim to only pull new tasks into UP NEXT at the weekly planning meeting.
3. 🎨 If anyone wants to explore something new, make a new task for it.
4. ⛏️ If any of these tasks are still nebulous or would take longer than a week, break them down into multiple more granular tasks.
5. 📎 Assign every task in the project board. Even if we don't know who will work on it, we can assign an initial point of contact who will look into the issue and reassign if needed.

Review

We follow this process as needed for every task where review is possible.

1. 🛑 When you feel finished or stuck on a task that you're assigned to, put it in review.
2. 🚧 Ask someone on the team to review your work that you think will give helpful constructive feedback or assistance.
3. 📎 Assign them as reviewer to your task, and provide any links or details needed for review with the item itself. This is better than sending it directly to your reviewer because you may need to call someone else in for assistance, or it may be helpful for management purposes to understand what resources connect to a particular task.
4. 🎉 Once they have reviewed your work, decide whether the task is now finished or needs more work. If it requires more work, put it back in progress and keep going. If it's finished, put it in done and move on to another task.

Updated a Manuscript?

Maintainers can trigger a new deploy of our data here and click "Run workflow". This process pulls in all of our annotated spreadsheets, puts them into our database and converts them to TEI. Then, the new data is published on the website. This process also happens automatically every time a code change is made on the main branch.