├── LICENSE ├── README.md ├── TODO.md ├── blank └── README.md └── guided └── README.md /LICENSE: -------------------------------------------------------------------------------- 1 | This is free and unencumbered software released into the public domain. 2 | 3 | Anyone is free to copy, modify, publish, use, compile, sell, or 4 | distribute this software, either in source code form or as a compiled 5 | binary, for any purpose, commercial or non-commercial, and by any 6 | means. 7 | 8 | In jurisdictions that recognize copyright laws, the author or authors 9 | of this software dedicate any and all copyright interest in the 10 | software to the public domain. We make this dedication for the benefit 11 | of the public at large and to the detriment of our heirs and 12 | successors. We intend this dedication to be an overt act of 13 | relinquishment in perpetuity of all present and future rights to this 14 | software under copyright law. 15 | 16 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 17 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 18 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 19 | IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR 20 | OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 21 | ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 22 | OTHER DEALINGS IN THE SOFTWARE. 23 | 24 | For more information, please refer to 25 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Template for a decent README.md 2 | 3 | A repository's README.md is the best gift you can give to a new developer. It gives them a brisk start to understanding what the repo is all about, what its purpose is, how to start coding and 4 | contributing, and most importantly how to successfully maintain the codebase and the app/software that is built from the code. 5 | 6 | This repository consists of two template files that serve slightly different purposes: 7 | 8 | [blank/README.md](blank/README.md) contains only the topics that a README.md could contain. 9 | 10 | [guided/README.md](guided/README.md) contains the topics and some guidelines and hints for the content of the topics. 11 | 12 | All software is different. No one ultimate README.md template can exist that would be a good fit for any software. This template can serve as a starting point for a good README.md, but it's up to the developer(you!) to use your own experience and consider what a new developer would want to see in the README. For example: 13 | 14 | * What are the things you would like to know when you start with a new repository and your job is to code, contribute and maintain it? 15 | * How you can save everybody's time by documenting things that would otherwise require digging in the code, hunting down an expert or just banging your head on the wall? 16 | 17 | This template can give you ideas about what a good README.md could contain, but it's not a "form" to fill. 18 | 19 | A README.md is written by a developer, to a developer. Be a good developer and write a README.md that you'd want to read. 20 | -------------------------------------------------------------------------------- /TODO.md: -------------------------------------------------------------------------------- 1 | It would be great if we could provide a complete example of README.md as a showcase. 2 | For now, we can use README.md from real customer projects as an example, 3 | but if we want to release this publicly available, we need an imaginary example. 4 | -------------------------------------------------------------------------------- /blank/README.md: -------------------------------------------------------------------------------- 1 | # OrangIT Standard Documentation 2 | ## Getting started 3 | 4 | ## Architecture 5 | 6 | ## Development 7 | 8 | ### Run tests 9 | 10 | ### Migrations 11 | 12 | ### How to make a production data dump and import it into the local development environment? 13 | 14 | ### Repository guidelines 15 | 16 | ## Test environment 17 | 18 | ### Access 19 | 20 | ### Deployment 21 | 22 | ### Logs 23 | 24 | ### Monitoring 25 | 26 | ## Production environment 27 | 28 | ### Access 29 | 30 | ### Deployment 31 | 32 | ### Verifying that a deployment was successful 33 | 34 | #### Automated test cases 35 | 36 | #### Manual test cases 37 | 38 | ### Rollback 39 | 40 | ### Logs 41 | 42 | ### Monitoring 43 | 44 | ## Continuous integration 45 | 46 | ## Operating instructions for manual and semi-manual processes 47 | 48 | ## More useful information, Tips and Tricks 49 | -------------------------------------------------------------------------------- /guided/README.md: -------------------------------------------------------------------------------- 1 | # OrangIT Standard Documentation 2 | 3 | Project purpose: What is the reason why this application exists? What real-world business cases does it support? 4 | 5 | ## Getting started 6 | 7 | Prequisites: 8 | - What other software you need to have installed on your local machine in order to set up a development environment? 9 | - Is there are separate file for environmental variables? 10 | - How does a developer get one that works? 11 | - Are other changes - such as /etc/hosts, port-forwardings - needed? 12 | 13 | Setup: 14 | - Install dependencies and other initial setup steps e.g. `docker-compose up` and `npm install`. 15 | - How to start the application locally e.g. `npm start`. 16 | 17 | Access the application locally: 18 | - What URL(s) to use to access the locally running application? 19 | - What kind of credentials do you need to access all relevant pieces of the application? 20 | - If there are multiple distinct user roles, you need a test user account for each of them. 21 | 22 | ## Architecture 23 | 24 | High-level architecture: 25 | - what is deployed and where, what are the main integration points? 26 | - What are the main languages/technologies used? 27 | - What kind of data is stored and where? 28 | - Don't hesitate to use a picture. 29 | 30 | ## Development 31 | 32 | ### Run tests 33 | 34 | - How to run tests locally? 35 | - Are there unit tests? 36 | - Are there integration tests? 37 | - Are there e2e tests? 38 | 39 | Describe here how to run any/all of them. 40 | 41 | ### Migrations 42 | 43 | How to run database migrations locally (if necessary). Sometimes the migrations are run as part of the test suite, which is preferable. 44 | 45 | ### How to make a production data dump and import it into the local development environment? 46 | 47 | Sometimes you run into hard-to-reproduce bugs, which manifest themselves only with production data. 48 | 49 | In those cases it is extremely useful to be able to do a data dump from production and set up the local 50 | development environment with production data. 51 | 52 | Describe how to do that here. 53 | 54 | ### Repository guidelines 55 | 56 | If using git: 57 | - What kind of git workflow is used in this project. Merge or rebase? 58 | - Should commits be squashed, and if yes, in which circumstances? 59 | - What are the requirements for commit messages? 60 | - What are the naming conventions for branches? 61 | - All other git-related stuff that comes to mind. 62 | 63 | If using some other version control than git: 64 | - The same as above, as is relevant to the version control system in use. 65 | 66 | Code style: 67 | - Coding conventions, linting, etc. 68 | 69 | ## Test environment 70 | 71 | ### Access 72 | 73 | - The URL where the test environment of the application can be found. 74 | Also, all other URLs which point to something relevant, like for example an administrator UI, etc. 75 | - The credentials to use in the test environment. For example, username and password. If there are multiple 76 | distinct user roles with different access to some parts of the application, there must be multiple developer accounts 77 | in order to be able to test all of them. 78 | - If a VPN, SSH tunneling or some other similar way to access the test environment is required, 79 | describe the steps needed here. 80 | 81 | ### Deployment 82 | 83 | - How a deployment is done. 84 | - The steps needed to verify that a new version is running in the test environment successfully. 85 | - Tests (scripts or otherwise) that you have to run in order to ensure that a deployment was successful. 86 | - Things that you have to test manually in order to ensure that a deployment was successful. 87 | - How to restore the previous version of the software when a deployment goes wrong? 88 | 89 | ### Logs 90 | 91 | Where are the logs, how to change logging levels, etc. 92 | 93 | ### Monitoring 94 | 95 | What kind of monitoring is there in the test environment, if any. 96 | 97 | ## Production environment 98 | 99 | ### Access 100 | 101 | - The URL where the production environment of the application can be found. 102 | Also, all other URLs which point to something relevant, like for example an administrator UI, etc. 103 | - The credentials to use in the production environment. For example, username and password. If there are multiple 104 | distinct user roles with different access to some parts of the application, there must be multiple developer accounts 105 | in order to be able to test all of them. 106 | - If a VPN, SSH tunneling or some other similar way to access the production environment is required, 107 | describe the steps needed here. 108 | 109 | ### Deployment 110 | 111 | How a production deployment is done. 112 | 113 | ### Verifying that a deployment was successful 114 | 115 | The steps needed to verify that a new version is running in production successfully. 116 | 117 | #### Automated test cases 118 | 119 | Tests (scripts or otherwise) that you have to run in order to ensure that a deployment was successful. 120 | 121 | #### Manual test cases 122 | 123 | Things that you have to test manually in order to ensure that a deployment was successful. 124 | 125 | ### Rollback 126 | 127 | How to restore the previous version of the software when a deployment goes wrong? 128 | 129 | ### Logs 130 | 131 | Where are the logs, how to change logging levels, etc. 132 | 133 | ### Monitoring 134 | 135 | What things are monitored? Which tools are used? How to access the UI(s) of the monitoring tools? 136 | 137 | ## Continuous integration 138 | 139 | Where is/are the CI(s) for this project? 140 | 141 | ## Operating instructions for manual and semi-manual processes 142 | 143 | Many applications require some manual processes which occur from time to time, like for example 144 | adding new users, doing manual database maintenance work, creating monthly reports etc. 145 | 146 | Describe how to do them here. The descriptions have to be detailed enough so that someone else can do them 147 | with these instructions. 148 | 149 | ## More useful information, Tips and Tricks 150 | 151 | - Other important or useful things to know. 152 | - Security considerations: Are there any specific things to consider regarding the security of the project, in addition to the usual best practices? 153 | 154 | IDE setup: 155 | - If there are some special tricks needed to get the project working in IDEA/Eclipse/something other, then 156 | describe them here. Preferably attach screenshots, if applicable. 157 | 158 | --------------------------------------------------------------------------------