Process
Git is the version control tool system we are using to work collaboratively and organise our project files. Our project is being hosted in a repository on GitHub (what you're on right now!). We have found GitHub to integrate much more effortlessly into our workflow than other alternatives like BitBucket.
Each new feature, change, or bug fix is implemented on a new branch. At least one review is required before it can be merged into the main branch.
Reviewers should refer to the requirements of the tasks the branch is addressing in order to determine whether it's in a good state to be merged.
Communication among the team is conducted through Discord, a free group chatting platform. Discord was chosen because, as a group primarily consisting of gamers, we have the most experience using Discord over alternatives like Slack. Furthermore, unlike Slack, Discord has voice and video sharing capabilities which make it much easier to collaborate online.
The Discord server is split up into several categories containing many channels dedicated to specific aspects of our project. As of 13/05/21, our server is split up into 7 categories:
- Important: Contains important links and information.
- General: Contains general information and discussions not specific to the project.
- Pitch: Contains discussions and information regarding pitches to supervisors and sound design students.
- Design: Contains discussions about the design of the game and the game design document (this wiki).
- Development: Contains discussions about the implementation of the game and any SWE40001-specific channels.
- Audio: Contains discussions about SFX and music within the game.
- Voice Channels: An area where we conduct weekly team meetings and collaborate.
Screenshot
Trello is a Kanban board used to manage the tasks that make up our project.
Tasks begin in the "Backlog" column and make their way through each of the columns as the task is worked on. All of the columns are:
- Backlog: Tasks that need to be completed but not urgently.
- Priority: Tasks that need to be worked on very soon.
- Doing: Currently working on the task.
- Ongoing: Tasks that are constantly being worked on over the duration of the project.
- Check/Review: Tasks that are awaiting someone to check it.
- Completed: Completed tasks.
A snippet showing the layout of our Trello board is shown below.
Each task has a list of requirements that need to be addressed in order for the task to be considered complete. Once complete, the task is moved to the "Check/Review" column where waits to be checked/reviewed by a fellow team member. It is then finally moved to the "Completed" column. The person who reviewed the task should state that in the description of the task (e.g. "Reviewed by Jordan").
Each task is given a label to categorise them based on what the task involves. As of 13/05/21, the labels being used are as shown below.
- Establish requirements for the task.
- Clarify design requirements with game designers and programming requirements with programmers.
- Ensure your local repository is up to date (pull from origin).
- Create a branch from main for the task. Name it concisely and appropriately (lowercase with dashes separating words).
- Commit frequently. Name each commit appropriately and concisely.
- Push your commits occasionally (after each work session and when you're ready to make a pull request).
- Create a new pull request on GitHub from the pull requests tab.
- Use an appropriate title that perfectly describes the pull request in a short statement.
- Describe what the pull request adds/removes/fixes/improves/etc. Include any information that would bring a fellow teammate up to speed with what the pull request achieves.
- If possible, include screenshots, GIFs, or videos to demonstrate what the pull request achieves.
- Include a link to the Trello card this pull request is for and link to anything else of relevance (e.g. GitHub issues).
- If necessary, provide reproduction steps to make it easy for others to replicate what the pull request resolves.
- If the pull request is not ready to be merged for any reason, assign the "incomplete" tag to the pull request.
- Publish the pull request. You're done!
Note: You are unable to merge your own pull requests.
- Checkout the branch of the pull request in your Git client of choice.
- Test the pull request by following any reproduction steps outlined.
- Attempt to ensure that no other features were broken by this pull request (regression testing).
- If the pull request has faults or doesn't address most, if not all, of the requirements in the Trello card, leave a review requesting changes with an explanation of what needs to be addressed.
- If the pull request is good and addresses all requirements, leave an approving review (with a kind message <3).
Feature pull requests must have an approving review from a designer and a programmer for them to be merged.
- When creating the merge commit, the default commit message is sufficient.
- Delete the branch after merging to keep the repository clean.
Issues:
- Commits are too infrequent and contain too many changes.
- Commit messages lack in detail or contain too much detail.
- There are too many unused branches sitting on the repository.
Solutions:
- Figure out what your next commit should achieve before starting to code. Then, once achieved, commit. Treat each commit as a little checkpoint on your way to completing the overall goal of the branch/pull request.
- A commit message should describe the goal of the commit on a surface level. If someone wants to know more, they can dive into the commit and view the code. Usually, the message should start with a verb (i.e. "fixed", "improved", "removed") and be one sentence.
- Continue deleting branches once they have been merged into main branch. Any other branches are the responsibility of the person who created it. Fortnightly, included in our regular team meeting, we should prune any abandoned and forgotten branches.
Issues:
- Revision history contains edits with the same default edit message.
Solutions:
- Add custom messages when editing pages. If you are finding that it's hard to describe everything you've edited in a concise message, consider splitting the edit into multiple edits. Each edit should be for a distinct reason so the revision history is clearer, similar to committing code to a branch.
Issues:
- Entries aren't descriptive enough for what they are tracking.
Solutions:
- Add more descriptive entry messages (without them becoming too long).
Issues:
- It is unclear who is reviewing tasks in the "Check/Review" column.
Solutions:
- State that you reviewed the task in the task description before moving it to the "Complete" column (e.g. "Reviewed by Jordan").
Issues:
- Meetings are unorganised and switch topic often.
- It is hard to identify where time is spent because individual time logs contain multiple labels.
Solutions:
- More structured meetings (put together a meeting agenda prior to the meeting)
- Stop Toggl when we move onto a different topic/task and ensure each individual time log has only one label assigned to it.
Issues:
- We are not providing task time estimates.
- We are not managing the risk associated with tasks. Furthermore, blocking points were difficult to identify with evidence.
- We lack a process for testing.
- The programmers are not checking with the designers before merging new features.
Solutions:
- Time estimates are to be added when a task is moved into the 'Doing' column on Trello. The actual time a task took to complete must be added to the task when the task is completed. Jake was assigned to collate and manages time estimates.
- A Trello power-up was added to allow us to track dependencies. Each teammate is responsible for identifying and adding the dependencies of the tasks they manage. Lachlan was assigned to manage risk.
- Jordan was assigned to implement and enforce a proper testing process.
- An approving review must be made by a designer on each feature pull request (on top of one from a programmer) before they can be merged.