Best Practices for SDL

Teams should adhere to the following practices, but may vary from them after consultation with the instructor:

• GitLab Configuration:

  • All students on each team should have Developer role. We can give them Maintainer role temporarily when required.
  • Disallow pushes to the main branch. This is ensured by going to Settings, Repository, Branch rules, view details, Manage in protected branches, and select No one for Allowed to push and merge. Allowed to merge will be set to Maintainers (or Maintainers + Developers).
  • Disallow squash commits: Settings, Merge requests, scroll down to Squash commits when merging, set to Do not allow. Save the changes.

• Issue Board settings

  • Visit Labels in the Manage tab. Use the New label button (top right) to create the labels In Development, Externally Blocked, and Ready for Review (in that order).
  • Visit Issue boards under Plan, click on the settings cog in the upper right corner, check that Show the Open list and Show the Closed list are set, Save changes if you had to set either.
  • Visit Issue boards under Plan, click on the New list button on the far right, set the Scope to Label, select the appropriate label under Select a label, click Add to board.

• Git repositories

  • Configure your git setup so check-ins and check-outs are as-is. This means git will not convert line endings between Unix/Window/Mac formats. The conversions are not needed since all modern editors can handle different formats. Allowing git often breaks deployment. You can set this by editing your .gitconfig file to include the text

    [user]
            autocrlf = false
    

  • Always push on each commit. That is, do not fall into the dangerous practice of doing lots of commits locally without pushing those changes to the Git server, otherwise you and your partners will have huge conflict resolution sessions that provide little value.

  • As discussed above, never squash commits. Squashing commits makes it impossible for instructors to determine who did what work, leading to lower grades. However, it is ok to delete branches; the critical commit history will still be available.

  • Never rebase a commit. Doing so increases the chances of losing code. The git commit history is not a valuable deliverable; focus on getting the code right rather than having beautiful commit histories. Use merges to combine branches.

  • If you do commit to main by accident, move the commit to the proper branch. You can either of the methods given by this page.

• Documentation

  • All deliverable documentation (other than the primary README) is to be in a doc folder in your project. Deliverables includes build instructions, testing instructions, design documentation, etc.; materials that will be needed by future teams to build, deploy, and maintain the system. Process documentation, such as sprint reports, are not deliverable.
  • The preference is that documenation be in Markdown format. It is easy to write, easy to maintain, and is easily viewed in the repository. Do not include HTML versions of markdown documents because that would be redundant with the markdown file, and redundant information creates inconsistencies.
  • Other documentation formats are acceptable (such as word processors, spreadsheets, movie files, etc.)
  • Organize documentation around themes, not file types. A folder called markdown is redundant information; use folders like “build instructions” or “deployment” instead. But you will probably find that having subfolders in your doc folder is unnecessary since you will likely have a relatively small number of documentation files.

• Design

  • Break the system into the three primary layers: data layer (domain classes/information in database), policy layer (code capturing the rules for the system), and GUI layer (the layer that interracts with the user).
  • Never write raw SQL into a project. Always use an object relational manager (ORM). They are available for almost all languages and platforms.
  • Do not put secrets in the repository. Information like passwords should be stored in environment variables used on the server and should never appear in the repository.