├── LICENSE └── README.md /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2015 Tyler Cross 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | 23 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Simple Naming Scheme 2 | > A simple naming scheme for developers. 3 | 4 | Having a naming scheme for all resources for a project is a must. This document outlines a simple scheme that seems to work well. Let's converge on something awesome. 5 | 6 | ## Goals 7 | Constructed names should be: 8 | 9 | - DNS-compatible 10 | - easy to read 11 | - expressive 12 | - sortable 13 | 14 | To make things really simple, just use a hyphen as a separator. This will be better explained. 15 | 16 | ## Tradeoffs 17 | 18 | - DNS-compatibility limits the valid character set 19 | - using hyphens as separators 20 | - makes this a potentially ambiguous grammar that can't be parsed reliably 21 | - makes the names super easy to read! (spinal-case) 22 | 23 | Global uniqueness of a name may or may not be important in some cases. Sometimes it's a requirement when using domain names and sometimes it's for convenience. For example, if there are multiple projects with multiple repos in one GitHub account. 24 | 25 | ## Naming 26 | 27 | The bits of information (parts) that can be used to name something are: 28 | - company name (ex: acme) 29 | - project name (ex: billing) 30 | - environment or flavor name (ex: stage) 31 | - role name (ex: api) 32 | - index (ex: 1) 33 | - location name (ex: AWS region) 34 | 35 | The scheme looks like this with (in general) least-to-most-specific going left-to-right: 36 | 37 | `company-project-environment-role-location-index` 38 | 39 | The least-to-most-specific order makes resource names sort together. We can leave off parts of the name as long as other resources of the same type do the same (ex: AWS security groups). 40 | 41 | **Scenario:** 42 | Acme Corp has a billing service with multiple environments, each in multiple locations. 43 | 44 | Here are some example resources and their names: 45 | - Git repo 46 | - `acme-billing-api` 47 | - AWS resources 48 | - EC2 instances 49 | - `billing-dev-api-1` 50 | - `billing-stage-api-1` 51 | - `billing-prod-api-1` 52 | - S3 buckets 53 | - `acme-billing-dev-api-us-east-1` 54 | - `acme-billing-stage-api-us-east-1` 55 | - `acme-billing-prod-api-us-east-1` 56 | - Security Groups 57 | - `billing-dev-api` 58 | - `billing-stage-api` 59 | - `billing-prod-api` 60 | - Domains 61 | - `dev-billing.acme-corp.com` 62 | - `stage-billing.acme-corp.com` 63 | - `billing.acme-corp.com` 64 | 65 | Using this naming scheme for domains actually removes the need to purchase an expensive wildcard cert for a project and each of its environments. 66 | 67 | ### Collaboration 68 | If there are any questions that need clarification create an issue. If your goal is to improve the naming scheme then please submit a PR! 69 | --------------------------------------------------------------------------------