Skip to content

Home

Jump to bottom
peteGSX edited this page Aug 30, 2022 · 17 revisions

Support-Planning

This repository is to capture all relevant documentation, processes, and workflows related to the DCC-EX project.

The goal of this repository is to enable consistent processes and workflows to track and visualise the various activities being undertaken as part of the project, without inhibiting creativity.

Automation and integrations are the preferred options where possible, with human interaction limited to adding/updating labels and information where required to allow the team to focus on creating value and "ooh shiny".

On This Page - Quick Reference

This page is a quick reference on:

Note: The diagrams on this page are created using Mermaid

Flowchart Legend

The below shapes are used in the various flowcharts on this page:

graph TD
  A([Start/end])
  B[/User input/]
  C[Manual task]
  D[[Automated process]]
  E{Decision}
  F[(Stored data)]
Loading

What are we asking the team to do?

In a nutshell, we are asking the entire DCC-EX team to:

  • Work in GitHub:
    • Create issues for development and documentation being done
    • You can brainstorm in Discord, Trello, where ever, but capture the output of what needs to be done in GitHub
    • Create GitHub branches from the GitHub issues (or at least link them in comments)
    • Label issues so others know what needs doing, in particular for documentation and testing
    • Ensure testing information and pertinent information for documentation is captured in GitHub issues
  • Use the DCC-EX Project Kanban board:
    • Multiple views have been created depending on your contributions
    • It's easy to see what activities are outstanding prior to a release
    • It helps keep documentation at the same pace as development (just add the Needs Documentation label with supporting info)
    • It helps ensure testing has been performed prior to release (just add the Needs Testing label)

That's it! As much as possible has been automated via GitHub workflows, however some minor administrative overheads will be required such as creating issues from the provided templates and adding/updating labels.

Development Processes

We abide by Git best practises, meaning new features and bug fixes are worked on in branches rather than directly in the master (or main) branch, committing and publishing work regularly, and submitting pull requests to ensure other team members have the opportunity to review changes prior to merging them into master (or main). If you need further information on this, refer to GitHub's Collaborating with pull requests page.

Use GitHub Issues

Ideally, each new feature or bug fix branch should be associated with a GitHub issue (see GitHub Issue Templates). These issues should be used to capture any related information that needs to be documented to ensure our documentation maintains pace with development.

For visibility, all GitHub issues will automatically be added to the DCC-EX Project Kanban board (see Using the DCC-EX Project Kanban Board).

If a GitHub issue requires documentation updates (every new feature probably should, bug fixes possibly not), then attaching the Needs Documentation label will bring it to the immediate attention of the Documenters via the DCC-EX Kanban board.

If a GitHub issue requires testing (they all probably should), then attaching the Needs Testing label will make it visible on the Testers view of the DCC-EX Kanban board.

Software Development Process

As an example, preparing for the next major release might look like this:

%%{init: { 'gitGraph': {'mainBranchName': 'master'}} }%%
gitGraph
  commit
  commit id: "RELEASE v4.0.0" type: HIGHLIGHT tag: "v4.0.0"
  branch next-release
  commit
  commit
  commit
  branch featureA
  commit
  commit
  checkout next-release
  branch featureB
  commit
  commit
  checkout next-release
  merge featureB tag: "v5.0.0, Unit Tested"
  checkout featureA
  commit
  checkout next-release
  merge featureA tag: "v5.0.0, Unit Tested"
  commit
  commit
  commit
  branch bugfixA
  commit
  commit
  checkout next-release
  merge bugfixA tag: "v5.0.0, Unit Tested"
  checkout master
  merge next-release tag: "v5.0.0, Regression Tested"
  commit id: "RELEASE v5.0.0" type: HIGHLIGHT tag: "v5.0.0"
Loading

When preparing for the next release, we create a new feature branch next-release from the existing master branch. Going forwards, all new features or bug fixes are branched from this next-release branch, leaving master as is.

After each new feature or bug fix has passed unit testing, it is merged into the next-release branch.

Once all new features and bugs are completed and regression testing has been performed, the next-release is merged into master (or main), and a new release can then be performed.

Website Update Process

Given our website is also managed in GitHub, we use branches and pull requests to manage updates in the same manner as our software development process does.

The website is hosted using GitHub pages, and therefore all updates need to be merged into the sphinx branch in order for the automated deployment workflow to be triggered to publish the updated version of the website.

%%{init: { 'gitGraph': {'mainBranchName': 'sphinx'}} }%%
gitGraph
  commit
  branch add-new-pages
  commit
  commit
  commit
  branch page1
  commit
  commit
  checkout add-new-pages
  merge page1
  branch fix-typo
  commit
  checkout add-new-pages
  merge fix-typo
  branch page2
  commit
  commit
  commit
  checkout add-new-pages
  merge page2
  checkout sphinx
  merge add-new-pages
Loading

When adding new pages to our website, we create a new branch add-new-pages as the basis for these updates. Each new page or update has a branch created and then merged back into this branch.

Once the updates are completed and local reviews validate the content is correct (Refer to our website contribution pages for more information), the add-new-pages branch is merged into sphinx, which triggers the automated website deployment workflow.

GitHub issue templates

GitHub issue templates are being deployed organisation wide to ensure sufficient information is captured when issues are raised, as well as apply appropriate GitHub labels to help draw the right team members' attention via the DCC-EX Kanban board and views. These will be deployed in the ".github" repository at the DCC-EX organisation level.

There are five issue templates to be deployed (see Issue Templates):

graph LR
  A(["Brainstorming (Trello, Discord)"]) --> B[/'Feature Request' issue template completed/] --> C[['Enhancement' label added]] --> D([New issue created])
  E(["Bug discovered"]) --> F[/'Bug Report' issue template completed/] --> G[['Bug' label added]] --> D
  H(["Documentation update required"]) --> I[/'Documentation Update' issue template completed/] --> JG[['Documentation' label added]] --> D
  K(["Help and support required"]) --> L[/'Support Request' issue template completed/] --> M[['Support Request' label added]] --> D
  N(["General task identified"]) --> O[/'To Do' issue template completed/] --> P[['To Do' label added]] --> D
Loading

Specific repository issue templates

If there is a need to have different issue templates for specific repositories, then these should be created in that repository only.

Using the DCC-EX project Kanban board

A DCC-EX Kanban project board has been created using a new GitHub Beta project for visibility of all activities across the project.

There is built-in automation of the Kanban, meaning minimal user interaction is required, and most of the moving of issues from one status to the next should be automated (see GitHub Project Workflows).

The various different views are driven by GitHub labels, so simply adding, updating, or removing labels is all that's required to bring issues to the attention of the right team members.

Project Kanban views

The DCC-EX Kanban project board has the below views available to help team members focus on what items they can contribute to, and what items are outstanding that need to be done.

  • Project Overview - Overview of all issues across all project streams
  • EX-CommandStation - All items labelled EX-CommandStation
  • EX-DCCInspector - All items labelled EX-DCCInspector
  • EX-Installer - All items labelled EX-Installer
  • EX-RAIL - All items labelled EX-RAIL
  • EX-Turntable - All items labelled EX-Turntable
  • EX-WebThrottle - All items labelled EX-WebThrottle
  • Documenters - All items labelled Documentation, Needs Documentation, Documented
  • My Items - All items assigned to the user viewing the Kanban
  • Testers - All items labelled Beta Testing, Needs Testing, Regression Tested, Unit Tested
  • Support - All items labelled Support Request

Automated GitHub Workflows

Several automated GitHub workflows are in use to take away as much manual interaction as possible from managing the Kanban board, deploying the website, and performing automated build tests where possible.

Automated build tests

Where possible, build tests run an automated workflow that performs PlatformIO builds of the software using GitHub Actions and workers.

graph LR
  A([Code pushed to repository]) --> B[[Trigger GitHub workflow]] --> C[[Launch GiHub worker]] --> D[[Checkout `master` branch]] --> E[[Install Python components and PlatformIO]]
  --> F[[Copy generic config]] --> G[[Run PlatformIO build]] --> H[[Notify success/failure via Discord webhook]] --> I([End])
Loading

Issue or PR to project workflow

When any issue or pull request is created in a repo with this workflow enabled, it is labelled according to what is defined in the repo secret REPO_LABEL, is added to the DCC-EX Project Kanban, and moved to "To Do" if it is a bug fix or support request, or to "Needs Review" if a review is flagged or it is a pull request.

graph LR
  A([New issue or PR created]) --> B[[Trigger GitHub workflow]] --> C[[Add repo label]] --> D[[Add issue/PR to project backlog]] --> E{Is it a bug report or support request?}
  F[(REPO_LABEL repo secret)] --> C
  E -->|Yes| G[[Move to 'To Do']] --> H([End])
  E -->|No| I{Is it a PR or an issue needing review?} -->|Yes| J[[Move to 'Needs Review']] --> H
  I -->|No| H
Loading

Website deployment workflow

The website is deployed via two different GitHub actions: the first being the build of the website using sphinx, the second being the built-in GitHub Pages deployment.

Website build workflow

When code is pushed or a pull requested is created against the sphinx branch, the build workflow is triggered, which results in the new website contents being pushed into the gh-pages branch, which will trigger the GitHub provided GitHub Pages deployment workflow.

graph LR
  A([Code pushed or pull request created on `sphinx` branch]) --> B[[Trigger GitHub workflow]] --> C[[Launch GitHub worker]] --> D[[Install Python packages]] --> E[[Checkout `sphinx` branch]]
  --> F[[Build GitHub docs]] --> G[[Push built docs to `gh-pages` branch]] --> H([End])
Loading

GitHub Pages deployment workflow

When enabling GitHub Pages on a repository, this workflow is enabled automatically by GitHub, and will trigger when code is pushed to the gh-pages branch, and therefore this workflow cannot be modified by the team.

graph LR
  A([Code pushed to `gh-pages` branch]) --> B[[Trigger Pages workflow]] --> C[[Build pages]] --> D[[Deploy pages]] --> E([End])
Loading

team ways of working.

Clone this wiki locally