Project Conventions

Organization

We use Github Issues to track what we're doing and future initiatives to take up. Don't be afraid to add issues to this list! These issues are then loaded into one of our Github Projects and assigned to someone. That person (or people) will create a branch off of whichever branch seems logical to branch off of, and do the work there.

READMEs, the Wiki, and Documentation

The images that are linked in the Runtime wiki are all in the runtime-docs Github repo.

Each major section of the code has it's own README, but READMEs shouldn't be too verbose. They should contain:

• Brief description
• Expected behavior
• A summary of the contents of the folder
• Dependencies
• How to build
• How to test / run

Any further explanations or discussions about design decisions should be in the corresponding Wiki page (which is part of the reason why there is so much information here).

If you feel that a diagram is necessary to explain your code, or if modifications to existing diagrams are in order, images should be added to the runtime-docs Github repo linked from the wiki. We encourage the use of images! (An image is worth a thousand words!)

Git

Try to squash your changes locally before pushing to Github, so that you don't clog up the public repo's history with small commits.

Commit messages should span multiple lines. Most people are taught to commit with git commit -m "<commit message>", but if you drop the -m flag and just run git commit, git will automatically bring up a text editor for you to enter multi-lined commit messages. The first line should be about 5 - 7 words, prepended with an all-caps tag enclosed in square brackets that describes the part of Runtime you were working on. Then, in the lines below, put a bullet-pointed list of items that were completed in that commit. Each line in this list should also be no more than about 10 words. These rules help the messages display well in git log commands as well as on Github. Here is an example:

[DEV_HANDLER] relayer() calls get_endpoints()

- Allows relayer to try every interface to get endpoints
- Relayer cancels threads only if no interface has the interfaces
- Removed INTERFACE_IDX (which was hardcoding)
- Future: Maybe try every setting on every interface

The tags we use are: [DEV_HANDLER], [NET_HANDLER], [EXECUTOR], [NETWORK_SWITCH], [SHM], [LOGGER], [LOWCAR], [SYSTEMD], [UTIL], [TEST], [DOCS], [BUILD], [FORMAT], and [MISC]. Hopefully it's clear what these tags mean!! (It would be a problem if the tags were confusing...)

When finished with the feature on your branch, submit a pull request to the branch that you branched off from and request the review of relevant people. Only after someone has reviewed your code and approved the pull request should you then merge (or rebase) your code onto your branch's parent branch (most often master).

Sprints and Demos

We do work in two-week cycles. At the beginning of each cycle (or "sprint"), everyone in the project sets goals for what they want to get done during that sprint. At the beginning of each meeting, everyone gives a short update on how they're doing, and what they intend to finish during that meeting. At the end of the cycle, each team member gives a demo of what they finished during that sprint, and the team gives feedback and evaluates the person's work. Of course, this requires the goals to be specific enough to demonstrate during a demo. For example, a goal of "I want to speed up the threads in dev_handler" is not specific enough. How will you demonstrate that during a demo? How will you quantify the speedup? How will you measure the speedup? In contrast, a goal of "The executor will be able to successfully terminate student code when Dawn disconnects" is specific enough. You can very clearly demonstrate that this occurs during a demo.

Coding Style

See our official style guide on the style guide wiki page.

The style guide is nit-picky and pedantic, we know. However, it really helps when everyone follows the same conventions throughout the entire project, to make it easy for people seamlessly transfer from working on one part of Runtime to another part. The whitespace conventions in particular help ensure that all of our code looks consistent on Github (some text editors display things differently than Github by default, so when multiple people work on the same file on text editors with different settings, the code ends up looking wonky on Github).

Luckily, most of the nit-picky things are automatically formatted by our format script, so right before you submit a pull request, make sure to run ./runtime format fix from the top-level directory so that your code conforms to the formatting portions of the style guide (that command won't automatically add comments or add new lines in the proper places, however—you still have to do that!!).