Múra’s Developer Guidelines

1 Initial steps

1.1 - Setup flutter repo (Android)

●​ In the Developer Onboarding folder you’ve just been given access to find the Adding
Signing Key.txt. The instructions will allow you to work with Firebase once you have the
repo cloned locally. The credentials go in: mura/android/key.properties

●​ In the same folder you will also find a Dummy Account Credentials file that will give you
an account to be able to log into the app for testing purposes. Use the “E-account”

●​ Now that you have the above information, clone the repository you now have access to
on Github locally and ensure you can run the app using flutter version 3.19.6, sign in
with the dummy account and click through some pages without any firebase
authentication errors​

●​ Update Android API Level to 35: Open android/app/build.gradle in your Flutter project.
Ensure the minSdkVersion and targetSdkVersion are set to an appropriate level (at least
API Level 35)​

●​ Request Trello access once you’re done with the above steps

1.2 - Setup flutter repo (IOS)

●​ Ensure you’re running flutter version 3.19.6 Run flutter doctor to check for any
missing dependencies and follow the instructions to resolve them. Install Xcode from the
Mac App Store and ensure CocoaPods is set up by running sudo gem install
cocoapods.
 ●​ Clone the repository to your local machine.

●​ Use the E-account from the Dummy Account Credentials file to sign in.

●​ Run the app and click through some pages without Firebase authentication errors

●​ Request Trello access once you’re done with the above steps

1.3 - Setup CF repo (update pending by Zubair)

2. Style Guide

●​ When making commits, we want to ensure that all changes to the code are intentional.

●​ Ensure that the auto-formatting in your IDE is not set to auto-format pre-existing code.
Here is an example of formatting settings in VS code that would be appropriate:

-​ Notice how only modifications are formatted on save.

●​ Tab size: 2

●​ Line Length: 100

●​ Try to match the style of our current widgets and classes as best as you can to ensure a
uniform and easy to read codebase.

3. Development Workflow
●​ Before beginning a task, ensure your local version of the project is up to date with the
master branch.
○​ Ex: git pull origin master

●​ When beginning a task, start a new branch with the same or a similar name to the Trello
task, which should be identical now to the master branch.
○​ Ex: git branch -b videos

●​ Make frequent, detailed commits. A commit should be done for at least each checkbox
item that is completed in the task, and possibly more frequently if the task is elaborate.
○​ Ex: git commit -m “Videos page now reloads when user uploads a new video.”

●​ At the end of your working session for the day (or more frequently if you prefer), push
your changes to the repo on the working branch for your task.
○​ Ex: git push origin videos

●​ During development, send design/functionality questions via WhatsApp.

○​ Before submitting a Pull Request, please send demos via screenshots and
screen recordings via WhatsApp for review in case of corrections or feedback.

●​ Before making a Pull Request to merge your branch into master, please ensure it is up to
date with the master branch and has pulled in all recent changes and resolved merge
conflicts
○​ Ex: git pull origin master (while on your non-master branch)
○​ This pulling from master can be done often to make development easier.

●​ When the task is fully complete and tested, make a Pull Request (PR).

●​ Leave comments explaining anything important outside of the commit history.

●​ After creating the Pull Request, you can check out another branch for a different task
while awaiting the current PR to be merged.
○​ NOTE: All new branches should be created out of the master branch. They
should not include any un-merged PR changes.
■​ Once you submit a PR, switch back to master, ensure it is up to date, and
then create your new branch off of master.

●​ If you receive any comments or requests during the PR code review:

○​ Check out the branch again and make any requested changes.

●​ Once the code is ready to be merged to master, that will be done by the code
reviewer.
 4. Task Overview

●​ Tasks are stored in Trello Cards

●​ There may be several bolded sections within a Trello card:

●​ Each block represents a feature and will be treated as 1 pull request.

●​ Typically, a task that is assigned to you will go under To do. Once you start working on
the task, move it under Doing. And when you’re done with the task, move it under Done.

●​ Pull requests should be fully tested and ready to merge into the master branch.

5. Reviewing and Merging PRs

You’re reading this section because you’ve been entrusted with the responsibility of merging
other developer’s pull requests. A proper review typically takes a few days before merge to
master. Note: whenever a branch is behind, it is best practice for the owner of the branch (not
the reviewer) to make it current. The reviewer can only assume this role when the owner is
unavailable.

●​ Go to changed files on Github and look through them 1 by 1; checking them off as you
go, and testing them in the app
 ●​ Ensure each piece of the functionality is working properly based on the developer’s task
on Trello and description of the commit. If any issue arises, submit a change request
and/or message the developer if it requires more instructions or questioning.

●​ Any small easy changes/corrections can be done by the reviewer to help the process
move quicker. Then inform the developer to review what you’ve done (after merge to
master) so the errors aren’t repeated next time.

●​ Ensure changes made in one area doesn’t negatively affect other areas that may be
connected to it

●​ Remove unnecessary codes (ensure the style guide in #4 above is followed), ensure
code is “snake cased” and ran via app constant in relevant areas.

●​ In rare instances developers mistakenly delete or unnecessarily comment other

developer’s code typical while fixing bugs. Ensure you clarify why these actions were
taken and reverse action were needed

●​ Once you’re satisfied with everything that is noted above, send a brief summary to the
boss (and include a demo if it's a new feature or something that looks different from what
you’ve seen before) before you then merge to master, delete the branch, inform the
developer of your successful merge and provide any relevant feedback.

●​ With no conflicts on the branch, you can merge by selecting “Merge pull request” on the
PR page > click confirm > Delete branch. If there are conflicts, the own of the branch
should be the one to remove them - not the reviewer.

6. Recovering lost code after merge

We've observed that when a pull request (PR) is merged out of order or without first pulling
changes from the master branch, most of the incoming code gets lost. Unfortunately, the only
solution at this point is a manual one. Here are the steps to follow:

●​ Create a new branch from the master branch.

●​ Navigate to the PR that caused the issue and retrieve the branch associated with it.

●​ Review all the changes made in each file and manually locate where the missing code
should be in the master branch.

●​ Similar to resolving merge conflicts, if you find missing code in the master branch, merge
the corresponding portion from the PR to fix it.
After each fix, review the changes again to ensure nothing is missing. Then, test to confirm that
all code has been recovered and is functioning as intended.

7. Unmerging a previous PR

To revert a merged pull request using `git reset`, `git checkout`, and `git push`, follow these
steps:

●​ Create a new branch from the master

●​ Identify the Commit to Revert To: First, identify the commit hash before the PR was
merged. You can do this by running: git log --oneline. And note the commit hash (let’s
call it `<commit-hash>`) you want to revert back to.

●​ Reset the Branch to the Desired Commit: Use git reset to move the branch pointer back
to the identified commit: git reset <commit-hash>. This command will reset your branch
and remove all commits after `<commit-hash>`.

●​ Force Push the Reset Branch: Since the history has been rewritten, you need to force
push the changes to update the remote branch: git push --force. Warning: Be cautious
when force-pushing as it can affect collaborators working on the branch

●​ Test and Verify: After the reset and force-push, ensure your branch is functioning
correctly by running your tests and reviewing the code.

●​ If everything looks fine, then remerge the branch with the master branch.

These steps allow you to effectively revert a merged PR and return the branch to its desired
state.

8. Reporting and Handling bugs

If you identify a possible bug, it is important you document and/or communicate it as soon as
possible - otherwise we run the risk of forgetting it. You can do one or more of the following to
properly address such:

●​ General documentation: publicly document the bug by adding it as a task to the “free
for all” checklist under “Touch-ups” card. Start the task with “BUG:” - ensure you leave a
detailed note.
●​ Fix now or later: if it’s a simple fix that wouldn’t stray you too far from your assigned
task, then fix. Otherwise if it’s something you want to get to later, add it to your named
checklist under “Touch-ups” - it must be added here so the team is aware.
●​ Assign: if the bug is unfamiliar or in an unfamiliar part of the code then communicate
with me and I’ll direct you to either assign it to a dev who has worked on it or add it under
“free for all”. Alternatively, you can communicate the issue with the group and another
dev can take it from there or inform you it has already been fixed on a different branch.