OSATE Development Guidelines

This is outdated! We no longer use Zenhub.

Managing issues

We use ZenHub to manage our issues. Use is free for open source projects. Among other things, Zenhub provides a Kanban board that we use as follows:

Newly created issues start as a card in New Issues. The card remains there until it is classified as a bug or enhancement. Then it can be moved to Backlog. To be able to track progress using the burndown card issues must have an estimate assigned. So far we use 1 as the estimate for all issues, i.e., we just count them.

Cards in Backlog represent items that need to be worked on. The cards here should have one label for the category (bug/enhancement/releng), the component (core, emv2, ge, ba, alisa, analyses) and importance (low, medium, high). Note that importance is NOT priority.

Use Next for prioritization. A card should be moved here once it has been decided to start work “soon.” The card may or may not have a milestone yet. Only issues with a milestone should be started and moved to In Progress.

Cards will be moved to Review/QA and Done automatically (see section "Working on issues").

There is one more column Stuck Issues which have been started but can't proceed for some reason. Move issues here to limit the number of In Progress issues.

Note: Release notes are generated via a script from the closed issues for the assigned milestone. The script collects only issues that have a component label or category:releng.

Issues and release notes

We are using the issue titles to generate release notes via a script. It helps a lot if everyone pays attention to issue titles.

When you add an issue or work on an issue, make sure that the title

1. actually states what's wrong (if it's a bug), or what should be changed (if it's an enhancement),
2. can be rewritten easily to state what has been fixed, and
3. has no spelling errors (sentence capitalization!).

It is OK to edit the title of an issue created by someone else to make it clearer.

Please remember that issues are also meant to be searchable by OSATE users that want to see if a bug they are seeing has already been reported. Using an issue as a "note to self" is not helpful.

If this is not done, creating release notes requires reviewing the issue text and comments to come up with a description of what has been fixed, which is boring and takes too long.

Examples

Bad: Issue with weight analysis

Better: Weight analysis ignores weight of processor components

Bad: Fault tree without modeling nature

Better: Fault tree analysis adds modeling nature to AADL project

Working on issues

Development of a bug fix of a new feature should always start from an issue, either a bug report or an enhancement request. Each issue should be addressed individually.

We use ZenHub to track progress, so you should install the ZenHub extension for your browser.

To address an issue follow these steps:

1. Select an issue, e.g., #4711 "Add priority and to FTA" to work on.
2. Take a moment to review the issue title. The title will show up in the release notes, so make sure it is descriptive.
3. Move the issue to 'in progress'.
4. Create a branch based on the latest master. The branch name should start with the issue number and add a couple of words that describe what is developed on this branch, e.g., "4711_priority_and." Try to be descriptive! "4711_fix" is not a good branch name. Remember that there are 10s of active branches.

   If you have write access to the OSATE repository create the branch there and not in a fork. This allows us to add commits to the PR if necessary.

5. Unless the issue is related to the UI you must create a JUnit test.
6. When you are done with development on the branch, create a pull request. In the PR do the following:
   1. In the description put the line "fixes #4711" (not "fixes issue #4711," etc, see https://help.github.com/en/github/managing-your-work-on-github/closing-issues-using-keywords for valid keywords). This will automatically close the issue when the PR is merged. It will also add a link to this PR to the fixed issue.
   2. You do not need to add a comment like "will be fixed by merging PR #xxx" to the issue.
   3. Connect the PR to the (correct!) issue (zenhub functionality). This moves the issue and PR together on the zenhub kanban board to the Review/QA column. If you accidentally connect the wrong issue, e.g., #4712 instead of #4711, to your PR you can change it, but make sure you put issue #4712 back in the correct column, e.g., Backlog or Next.
7. You can also create a PR it your work is still incomplete but you want to check if it builds without errors on Jenkins. Please mark such a PR as DRAFT until it is ready.
8. If you know who should review your PR, request a review in the UI. Github then sends a notification to the reviewer.
9. A reviewer may request changes. Re-request a review (icon next to the reviewer's name) when you have implemented the changes.

If an issue requires another issue to be fixed first use a zenhub dependency to indicate this. Similarly, if your PR requires another PR to be merged add a dependency to your PR.

After merging a PR, delete the PR branch. This can be done via github's UI.

Securing OSATE Development

Configuring git

Signing Commits

Signing your commits will make it impossible for someone who claims to be you to commit things to the repository in your name. Since many of our builds and deployments are automated, this could be a potentially serious security issue. If you already have a gpg key you use for email, you can reuse it here, or you can create a new key as part of this process.

1. To start with, you'll need a gpg key
   1. Check for one: https://help.github.com/articles/checking-for-existing-gpg-keys/
   2. Make a new one if you haven't already: https://help.github.com/articles/generating-a-new-gpg-key/
2. Tell git about your gpg key: https://help.github.com/articles/telling-git-about-your-gpg-key/
   
3. Make sure your key matches the email you use with git: https://help.github.com/articles/associating-an-email-with-your-gpg-key/
4. Turn on commit signing for all commits: https://help.github.com/articles/signing-commits-using-gpg/
5. If you're tagging releases, those should also be signed: https://help.github.com/articles/signing-tags-using-gpg/
   

Configuring github

Verifying Signed Commits

Telling github about your gpg key will enable automatic verification of your commits.

1. Add your gpg key to github: https://help.github.com/articles/adding-a-new-gpg-key-to-your-github-account/

Using Two-Factor Authentication

Two factor authentication will stop an adversary from wreaking all sorts of havoc if your password gets compromised.

1. Most people will want to use a TOTP mobile app: https://help.github.com/articles/configuring-two-factor-authentication-via-a-totp-mobile-app/

Protecting Branches

Protection will stop very destructive actions (ie, force pushes and deletes) from happening to the branch. It is also a prerequisite for a number of more fine-grained security measures.

1. Enabling branch protection is done through the github ui: https://help.github.com/articles/configuring-protected-branches/
2. Optional changes include requiring:

   1. Disabling pushes from particular people or teams: https://help.github.com/articles/about-branch-restrictions/

   2. Status checks: https://help.github.com/articles/enabling-required-status-checks/ including blocked merges when

      1. They cause the build to fail
      2. They aren't based off of the most up-to-date version of the base branch
      3. (see https://help.github.com/articles/about-required-status-checks/ and https://help.github.com/articles/types-of-required-status-checks/)

   3. Code reviews (including by a code owner): https://help.github.com/articles/enabling-required-reviews-for-pull-requests/

   4. Blocking edits from the web ui

   5. Requiring signed commits https://help.github.com/articles/enabling-required-commit-signing/