├── .gitignore ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── LICENSE ├── README.md ├── cmd └── README.md ├── internal ├── README.md ├── core │ └── README.md └── infra │ └── README.md └── pkg └── README.md /.gitignore: -------------------------------------------------------------------------------- 1 | vendor/ 2 | .idea/ 3 | .vscode -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | All notable changes to this project will be documented in this file. 4 | 5 | The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), 6 | and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). 7 | 8 | ## [[1.0.0](https://github.com/PerimeterX/go-project-structure/tree/v1.0.0)] - 2023-03-07 9 | 10 | ### Added 11 | 12 | - The full structure according to 2023-03-07 13 | - Documentation 14 | - Examples 15 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | 2 | # Contributor Covenant Code of Conduct 3 | 4 | ## Our Pledge 5 | 6 | We as members, contributors, and leaders pledge to make participation in our 7 | community a harassment-free experience for everyone, regardless of age, body 8 | size, visible or invisible disability, ethnicity, sex characteristics, gender 9 | identity and expression, level of experience, education, socio-economic status, 10 | nationality, personal appearance, race, caste, color, religion, or sexual 11 | identity and orientation. 12 | 13 | We pledge to act and interact in ways that contribute to an open, welcoming, 14 | diverse, inclusive, and healthy community. 15 | 16 | ## Our Standards 17 | 18 | Examples of behavior that contributes to a positive environment for our 19 | community include: 20 | 21 | * Demonstrating empathy and kindness toward other people 22 | * Being respectful of differing opinions, viewpoints, and experiences 23 | * Giving and gracefully accepting constructive feedback 24 | * Accepting responsibility and apologizing to those affected by our mistakes, 25 | and learning from the experience 26 | * Focusing on what is best not just for us as individuals, but for the overall 27 | community 28 | 29 | Examples of unacceptable behavior include: 30 | 31 | * The use of sexualized language or imagery, and sexual attention or advances of 32 | any kind 33 | * Trolling, insulting or derogatory comments, and personal or political attacks 34 | * Public or private harassment 35 | * Publishing others' private information, such as a physical or email address, 36 | without their explicit permission 37 | * Other conduct which could reasonably be considered inappropriate in a 38 | professional setting 39 | 40 | ## Enforcement Responsibilities 41 | 42 | Community leaders are responsible for clarifying and enforcing our standards of 43 | acceptable behavior and will take appropriate and fair corrective action in 44 | response to any behavior that they deem inappropriate, threatening, offensive, 45 | or harmful. 46 | 47 | Community leaders have the right and responsibility to remove, edit, or reject 48 | comments, commits, code, wiki edits, issues, and other contributions that are 49 | not aligned to this Code of Conduct, and will communicate reasons for moderation 50 | decisions when appropriate. 51 | 52 | ## Scope 53 | 54 | This Code of Conduct applies within all community spaces, and also applies when 55 | an individual is officially representing the community in public spaces. 56 | Examples of representing our community include using an official e-mail address, 57 | posting via an official social media account, or acting as an appointed 58 | representative at an online or offline event. 59 | 60 | ## Enforcement 61 | 62 | Instances of abusive, harassing, or otherwise unacceptable behavior may be 63 | reported to the community leaders responsible for enforcement at 64 | [opensource-conduct@humansecurity.com](mailto:opensource-conduct@humansecurity.com). 65 | All complaints will be reviewed and investigated promptly and fairly. 66 | 67 | All community leaders are obligated to respect the privacy and security of the 68 | reporter of any incident. 69 | 70 | ## Enforcement Guidelines 71 | 72 | Community leaders will follow these Community Impact Guidelines in determining 73 | the consequences for any action they deem in violation of this Code of Conduct: 74 | 75 | ### 1. Correction 76 | 77 | **Community Impact**: Use of inappropriate language or other behavior deemed 78 | unprofessional or unwelcome in the community. 79 | 80 | **Consequence**: A private, written warning from community leaders, providing 81 | clarity around the nature of the violation and an explanation of why the 82 | behavior was inappropriate. A public apology may be requested. 83 | 84 | ### 2. Warning 85 | 86 | **Community Impact**: A violation through a single incident or series of 87 | actions. 88 | 89 | **Consequence**: A warning with consequences for continued behavior. No 90 | interaction with the people involved, including unsolicited interaction with 91 | those enforcing the Code of Conduct, for a specified period of time. This 92 | includes avoiding interactions in community spaces as well as external channels 93 | like social media. Violating these terms may lead to a temporary or permanent 94 | ban. 95 | 96 | ### 3. Temporary Ban 97 | 98 | **Community Impact**: A serious violation of community standards, including 99 | sustained inappropriate behavior. 100 | 101 | **Consequence**: A temporary ban from any sort of interaction or public 102 | communication with the community for a specified period of time. No public or 103 | private interaction with the people involved, including unsolicited interaction 104 | with those enforcing the Code of Conduct, is allowed during this period. 105 | Violating these terms may lead to a permanent ban. 106 | 107 | ### 4. Permanent Ban 108 | 109 | **Community Impact**: Demonstrating a pattern of violation of community 110 | standards, including sustained inappropriate behavior, harassment of an 111 | individual, or aggression toward or disparagement of classes of individuals. 112 | 113 | **Consequence**: A permanent ban from any sort of public interaction within the 114 | community. 115 | 116 | ## Attribution 117 | 118 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], 119 | version 2.1, available at 120 | [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. 121 | 122 | Community Impact Guidelines were inspired by 123 | [Mozilla's code of conduct enforcement ladder][Mozilla CoC]. 124 | 125 | For answers to common questions about this code of conduct, see the FAQ at 126 | [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at 127 | [https://www.contributor-covenant.org/translations][translations]. 128 | 129 | [homepage]: https://www.contributor-covenant.org 130 | [v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html 131 | [Mozilla CoC]: https://github.com/mozilla/diversity 132 | [FAQ]: https://www.contributor-covenant.org/faq 133 | [translations]: https://www.contributor-covenant.org/translations 134 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # How To Contribute 2 | 3 | We'd love to accept your patches and contributions to this project. There are just a few guidelines you need to follow which are described in detail below. 4 | 5 | ## 1. Fork this repo 6 | 7 | You should create a fork of this project in your account and work from there. You can create a fork by clicking the fork button in GitHub. 8 | 9 | ## 2. One feature, one branch 10 | 11 | Work for each new feature/issue should occur in its own branch. To create a new branch from the command line: 12 | ```shell 13 | git checkout -b my-new-feature 14 | ``` 15 | where "my-new-feature" describes what you're working on. 16 | 17 | ## 3. Add documentation and examples for new or updated functionality 18 | 19 | - Please review the [README.md](README.md) file in this project to see if they are impacted by your change and update them accordingly. 20 | - If you've changed or added directories, make sure to provide or update their internal README file. 21 | - Once finished, make sure to create a dedicated pull request in the example branch, updating according to your change. 22 | 23 | ## 4. Add to CHANGELOG.md 24 | 25 | Any notable changes should be recorded in the CHANGELOG.md following the [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) conventions. 26 | 27 | ## 5. Submit a pull request and describe the change 28 | 29 | Push your changes to your branch and open a pull request against the parent repo on GitHub. The project administrators will review your pull request and respond with feedback. 30 | 31 | # How your contribution gets merged 32 | 33 | Upon pull request submission, your code will be reviewed by the maintainers. They will confirm that contribution policy has been followed. 34 | 35 | A (human) reviewer will need to sign off on your pull request before it can be merged. 36 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2023 HUMAN Security 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 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Go Project Structure 2 | 3 | go-project-structure-logo 4 | 5 | [![Licence](https://img.shields.io/github/license/perimeterx/go-project-structure)](LICENSE) 6 | [![Latest Release](https://img.shields.io/github/v/release/perimeterx/go-project-structure)](https://github.com/perimeterx/go-project-structure/releases) 7 | [![Issues](https://img.shields.io/github/issues/perimeterx/go-project-structure?logo=github)](https://github.com/perimeterx/go-project-structure/issues) 8 | [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md) 9 | 10 | This is a template repository for Go projects. 11 | 12 | We released a [blog post](https://www.humansecurity.com/tech-engineering-blog/finding-the-best-go-project-structure-part-1) revealing the story behind this structure. 13 | Our internal journey at HUMAN Security to find the best project structure, the decision we’ve taken, 14 | and the conclusions we’ve drawn along the way. 15 | 16 | To view a full example, navigate to the [example branch](https://github.com/PerimeterX/go-project-structure/tree/example). 17 | 18 | Each of the directories in this repository contains a README file describing its purpose. 19 | 20 | ## Contents 21 | 22 | - [Usage](#usage) 23 | - [Project Structure Design](#project-structure-design) 24 | - [Contact and Contribute](#contact-and-contribute) 25 | 26 | ## Usage 27 | 28 | To create a new project, fork this repository or [use it as a template repository](https://github.com/PerimeterX/go-project-structure/generate). 29 | 30 | ## Project Structure Design 31 | 32 | The project structure is designed with [independent packages](https://medium.com/@avivcarmis/ok-lets-go-three-approaches-to-structuring-go-code-42e2370c3ae5#92df) in mind, 33 | according to [hexagonal architecture](https://en.wikipedia.org/wiki/Hexagonal_architecture_(software)), and targeted to provide the following benefits: 34 | - Structural coherence 35 | - Separation of business logic and infrastructure 36 | - Reusability 37 | - Dependency declaration 38 | 39 | Fore more info, read the [full article](https://www.humansecurity.com/tech-engineering-blog/finding-the-best-go-project-structure-part-1) behind this structure. 40 | 41 | ## Contact and Contribute 42 | 43 | Reporting issues and requesting features may be done in our [GitHub issues page](https://github.com/PerimeterX/go-project-structure/issues). 44 | For any further questions or comments you can reach us out at [open-source@humansecurity.com](mailto:open-source@humansecurity.com). 45 | 46 | Any type of contribution is warmly welcome and appreciated ❤️ 47 | Please read our [contribution](CONTRIBUTING.md) guide for more info. 48 | -------------------------------------------------------------------------------- /cmd/README.md: -------------------------------------------------------------------------------- 1 | # `/cmd` 2 | 3 | Contains the different applications for the project. 4 | 5 | For each application, a directory should be created with the name of the desired executable (e.g., `/cmd/myapp`). 6 | 7 | Application code should be minimal, the business logic and infrastructure should be kept in `internal`/`pkg`. 8 | -------------------------------------------------------------------------------- /internal/README.md: -------------------------------------------------------------------------------- 1 | # `/internal` 2 | 3 | Contains code and packages we do not wish to share with other repositories and projects. 4 | -------------------------------------------------------------------------------- /internal/core/README.md: -------------------------------------------------------------------------------- 1 | # `/core` 2 | 3 | The business logic layer of the project, divided into packages by business domains. 4 | -------------------------------------------------------------------------------- /internal/infra/README.md: -------------------------------------------------------------------------------- 1 | # `/infra` 2 | 3 | Contains the infrastructure layer of the project, divided into packages by technologies or infra domains. 4 | -------------------------------------------------------------------------------- /pkg/README.md: -------------------------------------------------------------------------------- 1 | # `/pkg` 2 | 3 | Contains code we wish to share with other repositories and projects. 4 | As opposed to others, this directory will be visible and importable from other repos. 5 | --------------------------------------------------------------------------------