Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 17 Next »

Preparation

Environment setup

Spordle Play uses a devcontainer based environment which runs in Docker through VS Code. This helps keep developer environments in sync and reproducible, and avoids clashing with anything else you’re working on if you’re working on other projects.

The devcontainer is configured with docker-compose to automatically sets up an environment with containers for nodejs, Postgres, RabbitMQ, and Minio with the correct versions. Compose creates an internal network that allows containers to communicate with each other using their container names, which is useful to know for your app container.

If you have any of these services already installed, the container networking won’t conflict with existing ports and VS Code will automatically expose services to the next available port, while the standard ports are used within the devcontainer environment.

Windows

  1. Install WSL2 from the Microsoft Store and VS Code. You don’t need anything else! ✨

    • Docker Desktop is not necessary if you have WSL2 version 0.67.6 or higher (check wsl --version)

  2. Prepare WSL for docker. This may not be necessary in recent versions of Windows 11

    1. Enable systemd by updating /etc/wsl.conf to add:

      [boot]
systemd=true

    2. Restart WSL (via cmd)

      wsl --shutdown

  3. Install Docker. Follow Docker’s instructions to install docker-ce and docker-compose-plugin

    1. Once installed, add your user to the docker group for later convenience

      sudo usermod -aG docker $USER

  4. Clone the Play repository

    cd ~
git clone git@github.com:Spordle/Play.git play

  5. Open it in VS Code

    code ~/play

  6. Relaunch in the devcontainer

    • You’ll see a notification in the bottom-right corner suggesting this

    • You can also relaunch via the Ctrl-P menu by searching for ‘dev containers’

    • This might take some time as it’s pulling and building a few docker images for the first time

    • If it fails to launch, the bottom-right notification lets you open the logs to see what the error is exactly. The error popup is usually vague and super misleading.

  7. Follow README.md for further instructions on how to install and build Spordle Play

  8. Create a branch and open your first pull request! 🎉

macOS

TODO

Likely similar instructions above but with Docker Desktop

How we work

Play is a remote agile team that’s distributed across different cities, provinces and timezones, just like the users we build for.

To make this work effectively, we use agile sprints to keep ourselves organised and regular communication throughout the process is crucial.

Development guidelines

  • Branching is kept simple; there is no develop branch or any release branches, just master. The golden rule is that master must always be in a production-ready state. 🚀

    • Why? A code repository is meant for code, and continuous integration tools are meant for deployments and release management. While you can do a lot with git and branching, mixing these responsibilities creates a lot of unnecessary overhead and can provide a false sense of security for developers to merge incomplete work.

  • Play is a full-stack team working in a monorepo with JIRA stories designed to be completed within a single branch for all components (API, apps, etc). 🚄

    • The goal is to be able to review a single pull request and be able to checkout and test that branch easily. We want to be fully confident that a branch is ready to be merged and the story is able to be considered done so it can be shipped and we can move onto the next story.

  • Depending on the nature of the work, we may decide to gate functionality behind flags. This allows us to finely manage releases in the deployment process. 🚉

    • Some work inevitably needs to be done in stages, as we need to break up epics into more manageable stories. If it doesn’t make sense to expose something to users early on, or we only want to expose it in staging initially, flags are a useful tool to manage this.

  • When working on a story/branch, open a draft pull request early on! Once you’ve completed your work, you can mark the pull request as ready for review. 👀

    • Draft PRs provide opportunities for early and continuous feedback, and allows you to share what you’re working on with others to ask for help and collaborate together.

Agile process

  • Daily standups

    • This is a quick opportunity to share what you’re up to, flag any blockers, and ask for help. This keeps everyone in sync and also provides visibility to everyone as to what the team is actively working on.

    • Since we’re distributed across timezones, we use a daily Slack thread for async updates instead of having a meeting later in the day

  • Backlog refinement

    • Prior to sprint planning, we regularly review the backlog to ensure stories are still relevant and to give us an idea of what’s coming so we can plan the upcoming sprint

    • We use planning poker for all developers to assign points to each story using a Fibonacci scale, which indicate the amount of effort (not time) that each story requires to develop

  • Sprint planning

    • Before starting a sprint, we have a meeting to determine what everyone will be working on for the next two weeks. Stories from the backlog are selected by each developer based on the point assigned to them during refinement

    • Developers are encouraged to have autonomy over the stories they choose from the backlog. This process is guided by the number of points they feel they can successfully deliver within the sprint timeframe and priorities set out by stakeholders as determined during other meetings

  • Retrospectives

    • We continuously deploy our work and continuously improve our process. Retrospectives are an important step in the agile process to determine what works and what doesn’t work. Most importantly, this is a blameless process and faults no one as we seek to improve things for everyone

    • We hold a formal meeting at the end of each sprint and an quick informal one midway through the sprint as a health check

  • Sprint review

    • We have an internal review weekly to keep developers in sync and share what’s going on. More eyes on each other’s work often helps find issues before users do.

    • We have an meeting near the end of each sprint to showcase our work to stakeholders and gather some feedback to make sure business and developers are still in sync

This process is a work in progress. While Spordle is still relatively new to agile, we will likely always consider this process to be a work in progress and flexible to change to adapt our changing needs.

Communication

  • Prefer using channels and groups over direct messages

    • Don’t hesitate to work and discuss in the open so that the team has an idea of what you’re working on and can also learn from what you’re doing

    • While communication in channels is encouraged, that also doesn’t mean participation from everyone is expected in every discussion

  • As we’re a distributed team, we default to asynchronous communication

    • This acknowledges that people may be tied up with something else at the moment or in another timezone and having lunch

    • Likewise don’t feel pressured to respond immediately when you see a message if you’re in the middle of something

  • It can also be more effective to start a quick huddle or Meet call

    • Sometimes you need a quick response, or you find yourself going in circles in a chat, or you want to share a screen

  • No labels