Scribd
Upload
142 views4 pages

MMG GitHub Repository Naming Convention

This document provides guidelines for naming GitHub repositories and describing repositories in Mott MacDonald's global GitHub organization. It recommends that repository names use lowercase alphanumeric characters divided by dashes, be concise and memorable. Repository descriptions should be descriptive, readable, contextual and concise. The document also recommends classifying repositories with topics to help others find projects.

Uploaded by

Alexandre Rodrigues
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
142 views4 pages

MMG GitHub Repository Naming Convention

This document provides guidelines for naming GitHub repositories and describing repositories in Mott MacDonald's global GitHub organization. It recommends that repository names use lowercase alphanumeric characters divided by dashes, be concise and memorable. Repository descriptions should be descriptive, readable, contextual and concise. The document also recommends classifying repositories with topics to help others find projects.

Uploaded by

Alexandre Rodrigues
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 4

GitHub Repository Naming Convention

Prepared by: YJ Kim, Santiago Paz, James Walmsley, Date: 10 Mar 2022
Mirco Bianchini and Kate Molony

Approved by: Maria Mingallon 14 Mar 2022 Checked by: Chris Teolis 11 Mar 2022

Subject: Naming Convention Mott MacDonald GitHub repositories

1 What is a naming convention and why is it important?


A naming convention is a framework, general set of rules, or recommendations for naming things. Naming
conventions typically result in concise and descriptive names that are consistent across an organisation. This
is important because it allows members across an organisation to identify, manage, and share items with
increased efficiency.

2 Repository naming convention practices


To ensure the users in the Mott MacDonald Global (MMG) GitHub organisation collaborate as seamlessly as
possible, we encourage everyone in the organisation to adopt the following naming convention practices. For
any repository created in the MMG GitHub organisation, the repository should be named following some
simple requirements:

● Lower-case alphanumeric characters


● Words divided by “-”
Repository names can be indicative of the repository function or can also be unrelated and serve as an
interesting name for marketing. Good repository names rely on the common sense of the repository owner in
relation to how they want to organise their repositories.

Some points to remember when writing repository names:

● Concise
● Memorable
● Readable
There may be Team or community specific naming conventions that have more detailed requirements for
naming repositories within that Team on GitHub, so members should look for and follow additional
instructions on the GitHub Team discussion page. For example, see the Data Science Community GitHub
Team

An example repository name could be “azfunc-structure-optimiser”, this is a real repository that relates to an
Azure function based around optimising structure members. This repository name heavily relates to the
platform and function of the repository.

A larger project may have a more arbitrary marketable name such as “overleaf” which is a real product that
provides cloud-based document editing and storage services.

This document is issued for the party which commissioned it and for specific purposes connected with the above-captioned project only.
It should not be relied upon by any other party or used for any other purpose.

We accept no responsibility for the consequences of this document being relied upon by any other party, or being used for any other
purpose, or containing any error or omission which is due to an error or omission in data supplied to us by other parties.

This document contains confidential information and proprietary intellectual property. It should not be shown to other parties without
consent from us and from the party which commissioned it.
Mott MacDonald 2

3 Repository Descriptions
The most important aspect for naming repositories is the repository description. This allows the owner to
describe the repository which is used by the GitHub search engine when a GitHub user searches the Mott
Macdonald GitHub for repositories. When a series of search results are returned, the repository descriptions
are shown to the user for them to sift out the useful repositories.

Therefore, a repository description should consider the following characteristics in reference to the repository
content:

● Descriptive
● Readable
● Contextual
● Concise
Some example generic terms to consider that can relate to the overall functionality or operating platform of
the repository:

● Library: A supporting library of functions, e.g., a series of Python classes/methods that share a theme.
● API: A collection of API functions/endpoints.
● Workflow: A workflow of steps that accomplish some output given an input.
● App: An application, expected to be deployed as distributed software or as a cloud solution.
● Tool: Specific to grasshopper/dynamo.
● Plugin: Extends an existing piece of software.
These characteristics for a repository description are important as it allows a person browsing repositories to
quickly ascertain the nature of a repository. It also helps to optimise repository search results.

Here is an example of a repository with a contextually related name and good description that aids a user
searching for repositories related to the Moata Carbon Portal:

Figure 3.1: Moata Carbon Portal repository search

Source: Mott MacDonald Global GitHub organisation

Some of these repository names contain abbreviations related to the Moata Carbon Portal but all the
repository descriptions fit the given considerations allowing a user to easily find useful repositories.
Mott MacDonald 3

4 Classifying repositories with topics


To help other people find and contribute to your project, we highly encourage you to add topics to your
repository related to your project’s intended purpose, model algorithms, data type, etc. Please refer to this
GitHub doc for more details.

Here are some examples of topics (prior descriptors apply also). If none of the examples apply to your
repository, please suggest your topic and we will update the table below accordingly.

Every team is welcome to define their own topics extending from this basic list and publish them on
the GitHub team discussion.

Table 4.1: Topic type examples

Sector Practice Type Language


● Advisory ● Asset-Management ● C#
● Built Environment ● Building-Services ● Python
● Energy ● Climate-Change ● C++
● International Development ● Digital-Delivery ● VB
● Transport ● Java
● Water See the Practice Directory for ● Javascript
the full list of practices. ● Matlab
● Grasshopper
● Dynamo

To add topics to your repository:

1. On GitHub.com, navigate to the main page of the repository.


2. To the right of "About", click setting symbol.

Figure 4.2: How to add topics to your repository

Source: Mott MacDonald Global GitHub organisation

3. Under "Topics", type the topic you want to add to your repository, then type a space.
4. After you've finished adding topics, click Save changes.
Mott MacDonald 4

Examples of topics highlighted in red box

Figure 4.3: MPlaces

Source: Mott MacDonald Global GitHub organisation

Figure 4.4: Sandbox

Source: Mott MacDonald Global GitHub organisation

Figure 4.5: PowerBIgit

Source: Mott MacDonald Global GitHub organisation

You might also like