Development Process (How to Merge Changes)

Naming Conventions for GitHub Pull Requests

  1. The first term is a main feature of Artemis and is using code highlighting, e.g. “Programming exercises:”.

    1. Possible feature tags are: Programming exercises, Modeling exercises, Text exercises, Quiz exercises, File upload exercises, Lectures, Exam mode, Assessment, Discussion, Notifications. More tags are possible if they make sense.

    2. If no feature makes sense, and it is a pure development or test improvement, we use the term “Development:”. More tags are also possible if they make sense.

    3. Everything else belongs to the General category.

  2. The colon is not highlighted.

  3. After the colon, there should be a verbal form that is understandable by end users and non-technical persons, because this will automatically become part of the release notes.

    1. The text should be short, non-capitalized (except the first word) and should include the most important keywords. Do not repeat the feature if it is possible.

    2. We generally distinguish between bugfixes (the verb “Fix”) and improvements (all kinds of verbs) in the release notes. This should be immediately clear from the title.

    3. Good examples:

      • “Allow instructors to delete submissions in the participation detail view”

      • “Fix an issue when clicking on the start exercise button”

      • “Add the possibility for instructors to define submission policies”

Steps to Create and Merge a Pull Request

0. Precondition -> only Developer

1. Start Implementation -> only Developer

2. Implementation is “done” -> only Developer

  • Make sure all steps in the Checklist are completed.

  • Add or update the “Steps for Testing” in the description of your pull request.

  • Make sure that the changes in the pull request are only the ones necessary.

  • Mark the pull request as ready for review.

3. Review

Developer

  • Organize or join a testing session. Especially for large pull requests this makes testing a lot easier.

  • Actively look for reviews. Do not just open the pull request and wait.

Reviewer

  • Perform the “Steps for Testing” and verify that the new functionality is working as expected.

  • Verify that related functionality is still working as expected.

  • Check the changes to
    • conform with the code style.

    • make sure you can easily understand the code.

    • make sure that (extensive) comments are present where deemed necessary.

    • performance is reasonable (e.g. number of database queries or HTTP calls).

  • Submit your comments and status ((thumbs up) Approve or (thumbs down) Request Changes) using GitHub.
    • Explain what you did (test, review code) and on which test server in the review comment.

4. Respond to review

Developer

  • Use the pull request to discuss comments or ask questions.

  • Update your code where necessary.

  • Revert to draft if the changes will take a while during which review is not needed/possible.

  • Set back to ready for review afterwards.

  • Notify the reviewer(s) once your revised version is ready for the next review.

  • Comment on “inline comments” (e.g. “Done”).

Reviewer

  • Respond to questions raised by the reviewer.

  • Mark conversations as resolved if the change is sufficient.

Iterate steps 3 & 4 until ready for merge (all reviewers approve (thumbs up))

5. Merge

A project maintainer merges your changes into the develop branch.