Merge pull request #1 from zambezi/v1

First draft of an (almost) universal project template

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,22 @@
+<!--- Provide a general summary of the issue in the Title above -->
+
+## Expected Behavior
+<!--- If you're describing a bug, tell us what should happen. If you're suggesting a change/improvement, tell us how it should work -->
+
+## Current Behavior
+<!--- If describing a bug, tell us what happens instead of the expected behavior. If suggesting a change/improvement, explain the difference from current behavior. Screenshots (where appropriate) more than welcome! -->
+
+## Steps to Reproduce (for bugs)
+<!--- Provide a link to a live example, or an unambiguous set of steps to reproduce this bug. Include code to reproduce, if relevant -->
+1.
+2.
+3.
+
+## Context
+<!--- How has this issue affected you? What are you trying to accomplish? Providing context helps us come up with a solution that is most useful in the real world -->
+
+## Environment
+<!--- Include as many relevant details about the environment you experienced the bug in -->
+* Version used:
+* Environment name and version (e.g. Chrome 39, node.js 5.4):
+* Operating System and version (desktop or mobile):

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,25 @@
+<!--- Provide a general summary of your changes in the Title above -->
+
+## Description
+<!--- Describe your changes in detail. Screenshots (where appropriate) more than welcome! -->
+
+## Motivation and Context
+<!--- Why is this change required? What problem does it solve? If it fixes an open issue, please link to the issue here. -->
+
+## How Was This Tested?
+<!--- Please describe in detail how you tested your changes. Include details of your testing environment, and the tests you ran to see how your change affects other areas of the code, etc. -->
+
+## Types of changes
+<!--- What types of changes does your code introduce? Put an `x` in all the boxes that apply: -->
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to change)
+
+## Checklist:
+<!--- Go over all the following points, and put an `x` in all the boxes that apply. If you're unsure about any of these, don't hesitate to ask. We're here to help! -->
+- [ ] My change follows the style of this project
+- [ ] My change requires a change to the documentation
+- [ ] I have updated the documentation accordingly
+- [ ] I have read the [contribution guidelines](../CONTRIBUTING.md)
+- [ ] I have added tests to cover my changes
+- [ ] All new and existing tests passed

AUTHORS.md

@@ -0,0 +1,14 @@
+Thank You!
+==========
+
+This project exists thanks to the tireless efforts of all who have contributed – directly, or indirectly – in one way or another. For your time, effort, and expertise – thank you!
+
+The following shell script will print a list of all contributors to this repository's history:
+
+```bash
+git log --pretty="%aN" | sort | uniq
+```
+
+---
+
+[Full list of contributors](../../contributors).

CONTRIBUTING.md

@@ -0,0 +1,56 @@
+Contributing to This Project
+============================
+
+You're very welcome to contribute to this project! By making your contributions available, you implicitly agree to the contribution terms set forth in this document. If you do *not* approve of these terms, you must *not* make contributions to this project.
+
+Issues
+------
+
+Issues and enhancement requests are very welcome, as well as general discussion. Simply [create a new issue](../../issues/new) to get the discussion started!
+
+Contributing
+------------
+
+This project follow the "fork-and-pull" model of open source development:
+
+1. **Fork** the repo on GitHub
+2. **Clone** the project to your own machine
+3. **Commit** changes to your own branch
+4. **Push** your work back up to your fork
+5. Submit a **Pull request** so that we can review your changes
+
+**NOTE**: Be sure to merge the latest upstream changes before making a pull request!
+
+Copyright & Licensing
+---------------------
+
+Please see the [license](LICENSE.md) for detailed licensing and copyright information.
+
+We do not require you to assign the copyright of your contributions, and you retain the copyright. However, in order to be included in this, and potentially other projects, your contributions *must* also be made available under the same [license](LICENSE.md).
+
+If you do *not* agree with these terms, you must *not* make your contributions available. Unless *explicitly* stated otherwise, you agree to these terms simply by making your contributions available.
+
+### FAQ
+
+**Q:** I'm contributing on behalf of my employer, is this ok?  
+**A:** So long as you have the legal authority to make contributions and your employer agrees with the terms, we will happily accept contributions!
+
+**Q:** Can I contribute code or other material created by others?  
+**A:** Maybe, but please *do not assume you can*. Any contributions you make must be made available under the [same license as the project](LICENSE.md) and you *must* make sure you have the legal authority to make this contribution. If in doubt, please refrain from contributing or contact the original author to get their explicit approval.
+
+**Q:** Can I contribute code or other material under a different license?  
+**A:** No. Any contributions *must* be made available under the [same license as the project](LICENSE.md).
+
+**Q:** What does your license even mean?  
+**A:** The license sets out the terms under which you may use or reference this project. If you're in any doubt about it you should definitely consider seeking legal advice from a lawyer or other legal representative.
+
+Code of Conduct
+---------------
+
+With any contribution to this, or other open source projects, please make every effort to make this a nice experience for everyone.
+
+Please **be open** with your contributions, by not using private communications whenever possible. Also **be concise**, and whenever long form discussions are required, add a summary where appropriate.
+
+Additionally, it's important to **assume good faith** when working together. Your way of working may be different from that of others, so try your best to **be collaborative** and assume you are working toward the same goals.
+
+As collaborators may be from any part of the world and of any cultural heritage, we ask that you **be inclusive** and most importantly **be respectful!** Harassment or abuse of any kind will *not* be tolerated.

LICENSE.md

@@ -0,0 +1,7 @@
+Copyright (c) 2016 The project contributors – see [AUTHORS](AUTHORS.md).
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

RATIONALE.md

@@ -0,0 +1,13 @@
+Zambezi Project
+===============
+
+Whenever you're starting a project, there are about a million questions that need to be answered – some of them inevitable end up having to be answered for every project:
+
+- What license should we pick?
+- How should we structure the readme?
+- Where do we put author information?
+- What about how to contribute back?
+
+Those questions, and some others, are what this template project is trying to answer. It's not universal – some projects will necessarily have to clone and heavily modify this template – but it's a solid starting point for almost any project, and certainly software development projects. It should also be useful as the foundation for other project templates.
+
+Ideally the information in this project template is kept as structured as possible, such that most of it can be processed not only by a human, but also by machines. For instance, the use of widely known file names such as [README](README.md) and [LICENSE](LICENSE.md) may be used by machines to pick out introductory documentation and license information, and the contents of [SUMMARY](SUMMARY.md) may be used to generate navigable documentation for various purposes.

README.md

@@ -1,2 +1,60 @@
-# project
-Zambezi project template
+Zambezi Project
+===============
+
+Whenever you're starting a project, there are about a million questions that need to be answered – some of them inevitable end up having to be answered for every project. This template attempts to answer the most common ones, providing a solid foundation for you to build on.
+
+Usage
+-----
+
+1. [Download the latest release](../../releases/latest)
+2. Extract the downloaded archive
+3. Follow the checklist below
+
+Do *not* clone this project, unless you intend to actually [contribute changes](CONTRIBUTING.md) which is more than welcome!
+
+### New project checklist
+
+The steps in this list should be considered mandatory, and the following section includes some information on additional files to keep an eye on.
+
+- [ ] Name
+
+      You may pick any name for your project, but as a guideline make sure it's concise and reasonably descriptive.
+
+      Some specific Zambezi tooling uses the `ez` prefix for fun and profit. This is usually done for CLI tooling, but may be used for other kinds of projects as well.
+
+- [ ] README (i.e. this file)
+
+      The README should answer the following questions:
+
+      - **What is this project anyway?** Make the introductory paragraph a short summary of your project. It'll probably be the summary of your [rationale](RATIONALE.md) – the file that justifies the project's existance.
+
+      - **How do I consume this project?** Any instructions on how to use your project, keep them front and center. If there is more than can fit in a simple step-by-step list, then summarize and link to further documentation.
+
+      - **How do I contribute to this project?**
+      For developers and those just looking to discuss, provide some [contribution instructions](CONTRIBUTING.md). Make sure that you include some short instructions on how to get started for developers. Again, keep it to a step-by-step list, and any further documentation separately.
+
+      - **What is the license?** For legal reasons, *all* open source projects *must* have a [license and copyright information](LICENSE.md). This template chose MIT because it's short and permissive, and a very popular open source license. You can choose another, but [make sure you've done your homework](https://opensource.org/licenses)!
+
+- [ ] RATIONALE
+
+      When you create a project, think about why you're creating it. The [RATIONALE](RATIONALE.md) is your project's justification – its reason for being. You can make this how long and involved as you'd like, but should really discuss the goals and ambitions of the project. The big picture, as it were. Try to avoid sweating the small things like implementation details, so this document stands the test of time. This should be the document you hold up your work against and say: does this fit the bill?
+
+### Files to keep updated
+
+- [SUMMARY](SUMMARY.md): This file is the summary of your project's documentation. Keep it concise. The default contents is a list of links – keep this, and add to it with sections relevant to your project. This effectively turns your summary into the sitemap of your documentation.
+
+- [AUTHORS](AUTHORS.md): This file should list and thank the authors of your project, in whatever form is appropriate. By default it's a simple thank you notice, followed by a link to the full list of contributors as determined by the repository history. Expand this any way you see fit.
+
+- [LICENSE](LICENSE.md): By default, all Zambezi open source projects use the MIT license. Unless you're switching to an altogether different license, the only thing you should ever consider modifying in this file is the copyright notice – everything else should stay as it is.
+
+Found an issue, or want to contribute?
+--------------------------------------
+
+If you find an issue, want to start a discussion on something related to this project, or have suggestions on how to improve it? Please [create an issue](../../issues/new)!
+
+See an error and want to fix it? Want to add a file or otherwise make some changes? All contributions are welcome! Please refer to the [contribution guidelines](CONTRIBUTING.md) for more information.
+
+License
+-------
+
+Please refer to the [license](LICENSE.md) for more information on licensing and copyright information.

SUMMARY.md

@@ -0,0 +1,8 @@
+- [Introduction](README.md)
+- [Rationale](RATIONALE.md)
+- [How to contribute](CONTRIBUTING.md)
+
+---
+
+- [Authors](AUTHORS.md)
+- [License](LICENSE.md)