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, though they can be given Maintainer role if needed.
  • Disallow pushes to the main branch. This is ensured by going to Settings, Repository, Branch rules, view details for either the master or main, Manage in protected branches, and select No one for Allowed to push and merge. Allowed to merge should be set to Maintainers + Developers.
  • Disallow squash commits: Settings, Merge requests, scroll down to Squash commits when merging, set to Do not allow. Save the changes.
  Because our instance is hosted on gitlab.com, there is no way to change the time zone for the project. Reports such as the burndown chart use UTC times, so to include work that was completed after 6 or 7 pm (depending on daylight savings time), you sometimes need to advance the date by a day, capture the chart, and then restore it to the previous day.
• Git repositories
  • 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.
  • Every project should have a doc folder at the top level capturing key project documentation such as design artifacts and installation steps. The wiki should be reserved for process-related items (like sprint reports, knowledge acquisition, etc.), but anything future developers will need to understand how to build, deploy, and run the code should be in the doc folder.
  • Every project should have a README file at the top level as described in the syllabus.
• Product Backlog Items (PBIs)
  • No PBI should be pointed so high that it is expected to take a full sprint. Always break those PBIs into smaller increments to ensure forward progress. Otherwise, you are not really using the Scrum process.
  • All PBIs must have acceptance criteria. Acceptance criteria are not tasks; they are effectively tests that must be satisfied before the PBI can be labeled as "done".
  • Strong acceptance criteria are written using the given/when/then format:
    • Given [the state of the system before executing the action],
    • When [the user does some action],
    • Then [the system displays some result or takes some action]
    For example, a PBI for adding numbers on a calculator might have the acceptance criteria Given the user has entered 5, +, 3, when the user presses the equals key, then the calculator sets the current computed value to be 8 and displays that on the screen. Note that it is best to use concrete inputs in your given/when/then statements, but not always feasible. Things to watch for:
    • A given clause along the lines of "given the user wants to...". User thoughts are not testable. The given clause should talk about the state of the software system prior to executing the action.
    • A given clause stating that the system is running. That should be assumed, along with the assumption that the user has access to computational devices and the earth is circling the sun. Identify preconditions that would impact the PBI in question directly.
    • A then clause along the lines of "now the user can take some action" or "now the user will see correct results". The then clause in an AC needs to be focused on the system, not the user.
  • At least one AC for each PBI must be in given/when/then format. Some AC are simple requirements; these need not be listed using given/when/then. Examples include format requirements or computation details. But use AC for specifying the basic functionality to be provided by the PBI.
  • User stories start "as a user..." (preferably using a more specific type of user when applicable). Developers are not users! In these cases, the story format may not be applicable. For example, "restructure the database to introduce join tables" probably does not lead to a project increment that would be visible to end users. If the restructuring is about improving speed, capture that in the story: the users would like a faster system. But if there is no way to make the refactoring visible to end users, just drop the user story format. This often applies to spikes as well; the developers might need to experiment with different ways to implement a portion of a system, but these are for the developer's benefit, not the user (at least not directly), so spikes sometimes do not follow the story format.
  • Because GitLab considers a PBI to be in development as soon as a developer is assigned to it, do not make the assignment until the developer actually starts to work on the PBI. Otherwise, it will appear the team has too many PBIs open at any one time. If it is important to track which person intends to do which PBI, you can tag the PBI with that person's name. However, this should not be general practice; it is assumed anyone on the team can work on any PBI, and it is important that PBIs be addressed in priority order.
• 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.
• Implementation
  • Avoid adding login features to your system too early. Logins are rarely very interesting - it's typically simply a question on how to use a library to validate a password, and adding a login requirement early in a project just means you have to type passwords over and over again while getting basic functionality to work. If you do have a login, strongly consider whether you can avoid the login step during development mode to speed up development.
  • Use programming language tools to create path names. For example, use path.join() in Javascript than hardcoding paths like xyz/abc.js. This allows your code to run under both Windows and Linux.