Practices
Add practices from the instance catalog, write your own, organize them in groups, and accept or decline catalog updates.
Practices are the engineering practices that Hephaestus checks your workspace's work against. Workspace admins and owners choose and edit them in Practice setup, under Administration → Practices. Members see the practices on their practice profiles.
Your practices and the instance catalog
The instance catalog holds the practices and practice groups that your instance admin includes. When you add a practice from it, your workspace gets its own copy. Your copy changes only when you edit it or accept a catalog update.
Each practice belongs to a practice group, or it is Unassigned. Groups organize the practices on practice profiles.
Each save creates a new version of the practice. Earlier observations keep the version that judged them, so your edits never rewrite history.
A badge on each practice tells you how it compares with the catalog:
| Badge | What it means |
|---|---|
| Same as the catalog | Your copy matches the catalog. |
| Edited here | Your workspace changed the practice. |
| Catalog update waiting | The catalog has a newer version. Your copy stays as it is until you decide in Catalog updates. |
| No longer in the catalog | New workspaces cannot add it. Your copy keeps working as it is. |
Add practices from the catalog
- Under Administration → Practices, open Practice setup.
- Select Show catalog.
- Select a practice, or select Add group on a group that your workspace does not have yet.
- Read what adding it does.
- Select Add practice. For a group, select Add with the number of practices.
The practice appears in its group, ready for review. Practice reviews and feedback mode explains how to turn on reviews and choose who reviews.
Create a practice
- In Practice setup, select Create practice.
- Enter Name * and choose a Practice group.
- Under Reviews, choose the kind of work. You cannot change it later.
- Under Review guidance, write What to look for *.
- Choose Reviewed by.
- Under When this practice is reviewed, choose the events, the states, About, and Reads.
- Optional: add conditions under Applies when, and write Otherwise *.
- Select Create practice.
To change a practice later, open More actions on the practice, then select Edit practice. Select Save changes to save a new version.
Review guidance
Write What to look for * as a positive standard: what the work must do to meet the practice. Describe each required behavior once. An optional improvement is not a problem. A broad claim needs evidence for all the work that it covers.
Why it matters, What good looks like, and Going well are guidance for developers. They do not change how the practice is reviewed. Going well is shown to a developer whose work meets the practice.
Reviewed by
| Choice | What happens |
|---|---|
| Hephaestus | An automated review reads the work and records an observation. When a source that it must read cannot be captured, the review is withheld. |
| People | A developer, peer, or mentor reviews the practice. No automated review runs. Describe what the review cannot support. |
| Nobody | The practice offers guidance without a review. |
Your own practice runs beside the catalog practices, and nothing compares them. Two practices that judge the same concern can give opposite results on the same work. Keep one of them, and set Reviewed by of the other to Nobody. The feedback mode Off stops feedback, but reviews still run.
When this practice is reviewed
Review on selects the events that start a review, such as Opened, Marked ready for review, New commits pushed, or Merged. When selects the states of the work that a review accepts, such as Draft status and State. A requested review also follows these settings.
To comment on a draft once it is ready, a practice needs Marked ready for review, as Control when feedback reaches the work describes.
Checks finished reviews a pull request again when every check that GitHub listed has ended. A check that starts later can add a new review. If the checks never finish, or the push has none, no review starts for this event. Add Opened or New commits pushed if the practice must always run. Only GitHub reports checks. On GitLab, a practice that needs them is not reviewed.
About selects whose work an observation is about: Author, Reviewer, Assignee, or Whoever merged it. Choose The work when the observation is about no developer. If the role has no person, or more than one possible person, the practice is withheld for that work.
Reads lists the sources that a review uses. Set at least one source to Required, because a review cannot run without one. Must be captured whole lets the review say that something is missing from a source. With it, a partial capture withholds the review. A failure to capture a required source never becomes an observation.
Applies when
A practice with no condition applies to all work of its kind. A condition limits the work that it applies to:
- A file changed, with File paths, such as
**/*.swift. - The diff contains text, with Text to find.
- A source is not empty.
- The work has merged.
A review can start when any condition holds. If every condition is false, the observation is Does not apply, with your Otherwise * text. Missing or incomplete evidence never makes a condition false. Issues have no conditions.
Practice script
A practice uses the built-in practice script unless you add one under Script. A practice script can prepare the review, or decide from the captured records. If your script is not valid, the practice stops with a reason and never falls back to the built-in script. Practice script API lists what a script can use.
Practices for one technology
A practice has no technology field.
To limit a practice to one platform, add the condition A file changed with its paths, such as **/*.swift.
To make a catalog practice stricter for your course, edit your copy and save it.
Do not create one copy of a practice for each technology. The copies drift apart, and their observations stop being comparable.
Add a visual
A visual is one SVG picture and its description. The developer's practice panel shows it between Why it matters and What good looks like. Add one only when it shows the idea better than a sentence.
- Open the practice with Edit practice.
- In Visual, select Upload SVG and choose a file. You can also paste the markup into SVG markup.
- In Description *, say what the picture means. Do not describe its shapes or colors.
- Check the Light theme and Dark theme previews.
- Select Save changes.
To remove the visual, select Remove in Visual, then save the practice.
Hephaestus reads the description, never the picture. Thus, the description must give the full meaning. Practice visual rules lists the markup that Hephaestus accepts, the color classes, and starter templates.
Add a guide
A guide is a longer explanation in Markdown, with up to 4 figures. The developer opens it in the Guide tab of the practice panel.
- In Guide, write the text in Guide text.
- To add a figure, put the cursor where the figure goes.
- Select Add figure and choose an SVG file.
- In the new line, replace "Describe the figure" with what the figure means.
- Select Preview to check the text and the figures.
- Select Save changes.
To remove a figure, select Remove beside it. To remove the guide, select Remove guide, then save the practice. A link in a guide opens in a new tab.
Organize groups
- In Practice setup, select Create group to add a group.
- To change a group, open More actions on it. Select Rename, Move up, Move down, or Delete group.
- To move a practice, open More actions on it, then choose a group under Move to.
The switch on a group shows or hides it on practice profiles.
Review catalog updates
When the catalog changes a practice that you added, the change waits for you. Each workspace decides for itself.
- In Practice setup, select Catalog updates.
- Open an update.
- For each changed field, compare Base, Current, and Proposed. Conflict marks a field that both your workspace and the catalog changed.
- Choose Current or Proposed for each changed field.
- Select Accept selected fields, or select Decline this update.
Accepting creates a new version of the practice. Declining keeps your practice as it is until the catalog changes again.
Reset a practice to the catalog
- Open the practice.
- Select Reset to catalog.
- Read What the reset changes.
- Select Reset to catalog.
The catalog's version is saved as a new version of your practice. Earlier versions and their observations stay. On a group, Reset to catalog under More actions brings back the catalog's name, description, icon, and color.
Delete a practice
- Open More actions on the practice.
- Select Delete practice, and confirm.
CAUTION
Deleting a practice also deletes its observations. You cannot undo this. To stop a practice for a while, set its feedback mode to Off, or set Reviewed by to Nobody.