Project Management

Project Management#

This section has some tips and best practice for organizing a technical project.

You might want to start with the high level overview for the motivation behind these techniques.

Project Setup#

A checklist of some things to consider when starting a new project from a technical/tooling perspective (could apply to an existing project too):

  • Decide an access policy for project materials: private (members only), ICHEC Group (ops, systems, etc), ICHEC Internal, public. The materials should be by default as open as possible - only restrict access where necessary for e.g. security, IP, personal data protection purposes.

  • Make a Team in Microsoft Teams for collaborative document editing and file sharing. Add project members.

  • Make a Slack channel for project discussion, add project members and optionally leadership

  • Make a Gitlab group for project management (milestones, issues, wiki) and hosting project repos.

  • Write a project README in the Gitlab group giving some details on what it is, who is involved and the timelines.

  • Write a small blurb about the project (one or two paragraphs, what it is - who is involved, what is timeline) and post it to the office space. Include a link to the project README.

  • Add an entry to the ICHEC Handbook Active Projects pages (internal and/or public).

  • Set up a regular sync meeting for project participants

  • Keep minutes of each meeting, including them the Gitlab wiki

  • Maintain the project Milestones and Issue backlog in Gitlab

Software Project Tips#

Get the project in version control#

Some reasons for putting a project in version control with a remote host:

  • It is backed up for you

  • If you follow version control best practice you have reduced chance of losing work

  • It is the first step to automating your project’s outputs

  • When you sync to the remote frequently others can see and collaborate on your work

Track work with an Issue Tracker#

Complex projects should be broken down into a hierarchy of small tasks. Issue trackers, like available in GitLab, allow linking these tasks to actual work delivered and give a chance to collaborate and reflect on work done and priorities.

Use a standardized project structure#

They exist for most languages (Python, C++ etc) and frameworks (Django, Angular etc).

Advantages are:

  • Your work will fit better with automated tools including IDEs and CI/CD

  • Your colleagues will be able to understand the project more easily and onboard faster

  • You will likely be able to re-use the structure in other projects

Use automated testing#

Automated testing ensures that making code changes doesn’t have unintended consequences. It is important for all projects, but particularly those with collaborators or needing some notion of quality control (i.e. most projects).

Use Continuous Integration#

Continuous integration, among other benefits, automatically checks code changes so issues can be identified before merging. This allows collaboration on a shared project and easier project maintenance.

Stay platform agnostic as much as possible#

Avoid platform specific code where possible - if unavoidable try to ass mocks or stubs for platform specific functionality. Given that we often develop on Mac but deploy on Linux it is important to support both platforms. Developing in a VM on Mac is not fun - don’t make your colleagues do it.

Use reproducible build and runtime environments#

Your project should be runnable in a reproducible environment - such as a container. Anything that doesn’t run in a container should be mocked out and have a small surface area in the project. The mocked interface should have an automated test focus.

Make the project tolerant to change#

Be aware of Conway’s Law - if a project is run as a Waterfall there is a high chance the code structure will follow suit and will not be tolerant to change.

Advantages of code that is tolerant to change:

  • Can respond more easily to:

    • Security issues

    • Dependency changes

    • Feature requests

    • Bugs

  • Easier onboarding of new colleagues

  • Lower stress for new colleagues as changes aren’t necessarily ‘major’

  • Fewer ‘haunted graveyards’ - project areas everyone is afraid to touch

Agile/DevOps/Platform Engineering are approaches to help make projects more tolerant to change - but keep in mind that ‘doing agile’ as intended is about people and communication, not process. It is easy to define processes - it is hard to make fundamental changes to how people work together.

Contents