telus/reference-architecture

TELUS Reference Architecture Documentation

Why

Why does this exist?

This wiki is the source of truth for all technical knowledge, software specifications, standards and architecture evolution for TELUS.

The goal of the document is to track and discuss software standards, tooling and practices within TELUS. You are welcome to contribute and suggest changes. Please follow the contribution guidelines and keep in mind that this repository is open source.

Who

Who is this for?

• Existing Team Members reference and contribute to this document.
• Prospective Team Members learn about TELUS software development standards and practices.
• TELUS partners familiarize with TELUS software standards and practices prior to project delivery commitments.

What

What is the structure?

This is a public and open source repository. Articles are written in Markdown on topics in the following categories:

• Development
• Process
• API Platform
• Testing
• Delivery
• Security
• Performance
• Analytics
• Hardware & Tooling

Documentation is meant to be thin and simple. Members should be able to quickly and easily understand the whys, whats and hows of any part of our software standards.

How

How to take part?

Embody our Principles

• Focus on Customer First
• Value data over opinions
• Deliver outcomes over outputs
• Take risks and be lean
• Build for quality and reuse
• Be an owner
• Attract and develop leaders
• Embrace inclusivity
• Strengthen communities

Open Source

Because we love our customers and we love our technology, we are evolving it, in full transparency!

We do all of this in public to truly embrace our customer first principles

In order to achieve this, we ensure no sensitive content is included, such as:

• security & privacy policy violating content
• content considered competitive intelligence
• keys, tokens or credentials

Process & Contribution

To ensure open collaboration and support for wiki contributions, a few avenues are made available:

• Technology Forum
  The Technology Forum is the official discussion board for conversations around technology solutions, ideas, issue escalations, questions, knowledge sharing, and Reference Architecture evolution.

  Since Reference Architecture is open source, we separated Technology Forum into its own private repository for deep technical discussions and confidential information.

• Open Contribution
  Use GitHub to create pull-requests, start discussions, and contribute to active issues. Your contributions should also be addressed in The Technology Forum in order to be considered for adoption.

  If you are ready to start contributing, here are some things to keep in mind:

  • This a versioned documentation repository, and commit messages follow the karma format.
  • If you are adding new documentation or updating existing documentation, you should format your commits following this model: docs(<scope>): added/updated standards about <scope>.
  • If you are adding major sections or introducing major changes, then consider marking your commit as a breaking change.
  • If you are only making corrections or fixing style/layout/punctuation/grammar, etc., then follow this model: style(<scope>): fix grammar issues in <scope> docs.
  • For all other commits, follow the above mentioned Karma conventions.
  • Feel free to consult our CONTRIBUTING guide for more guidance on how to contribute.

Local development setup

If you want to make sure your changes will pass our CircleCI steps, you might want to run things locally:

npm run lint

In order to setup everything needed to run all of the checks locally, please run the script below. This will install locally all of the dependencies needed and mirror the CI setup:

npm run setup-local

Format

All topics MUST adhere to the format outlined in this template

GitHub

Using the GitHub repository itself, rather than the "GitHub Wikis" feature, or other "Wiki" software ensures:

• version tracking, and usage of GitHub GUI features (blame, history, branches, diff, etc ...)
• ability to publish into a static website using GitHub Pages
• leverage branch locking, testing automation and other GitHub features only available in repos

Conformance

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.