- Added a header images for the "root" based documents for GitHub related stuff.
- Edited files which include the new header image to reflect the doc's structure change.
- Improved the images included in README.md.
- General proof reading
The images should help improve the readability of the documents. And, they have begun to settle on a style which compliments the GitHub styling. This should be use for the Wiki part of the project.
Before submitting, please make sure your issue has not already been filed. You can do this at [GitHub Issues](https://github.com/craigoates/issues "GitHub Issues").
Note: Before submitting, please make sure your issue has not already been filed. You can do this at [GitHub Issues](https://github.com/craigoates/issues "GitHub Issues").
## Description
### Description
[Description of the issue. Use images and GIFs if necessary.]
## Steps to Reproduce
### Steps to Reproduce
[Use images and GIFs if necessary.]
@ -16,22 +16,22 @@ Before submitting, please make sure your issue has not already been filed. You c
1. [Second Step]
1. [and so on...]
## Expected Behaviour
### Expected Behaviour
[What you expect to happen]
## Actual Behaviour
### Actual Behaviour
[What actually happens]
## Reproduction Rate
### Reproduction Rate
[What percentage of the time does it happen?]
## Versions
### Versions
[You can get this information from using the Nuget Package Manager tools in Visual Studio/Project References.]
## Additional Information
### Additional Information
[Any additional information, configuration or data that might be necessary to reproduce the issue.]
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
## Our Standards
### Our Standards
Examples of behavior that contributes to creating a positive environment include:
@ -22,23 +24,23 @@ Examples of unacceptable behavior by participants include:
* Publishing others' private information, such as a physical or electronic address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a professional setting
## Our Responsibilities
### Our Responsibilities
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
## Scope
### Scope
This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
## Enforcement
### Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at craig@craigoates.net. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
## Attribution
### Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
Let me begin by saying thank you for stopping by and checking out Console.Waterworks.
The following is a set of guidelines for contributing to Console.Waterworks. I must stress, though, they are guidelines and nothing more. They are not set in stone. Please feel free to use your own judgement when contributing.
## Code of Conduct
### Code of Conduct
The [Console.Waterworks Code of Conduct](https://github.com/CraigOates/Console.Waterworks/blob/develop/CODE_OF_CONDUCT.md, "Code of Conduct") governs every participant of this project. If you decide to take part in developing and cultivating the project, the expectation is you to adhere to it.
The [Console.Waterworks Code of Conduct](https://github.com/CraigOates/Console.Waterworks/blob/develop/CODE_OF_CONDUCT.md, "Code of Conduct") governs every participant of this project. If you decide to take part in developing and cultivating the project, the expectation is you adhere to it.
Please report any unacceptable behaviour to [craig@craigoates.net](craig@craigoates.net, "Craig's email address").
## The Creator's Expectations for Console.Waterworks
### The Creator's Expectations for Console.Waterworks
To those who do not know, Console.Waterworks is the creation of Craig Oates (A.K.A. [me](http:github.com/CraigOates, "Craig's GitHub Profile")). I am a person, like you, and I argue it is important you know a bit about me. The reason why this is important is because it will help you gauge if this project is for you. I do not want you to feel frustrated when working on Console.Waterworks due to people problems. I know I cannot foresee every problem and counteract it. But, I can let you know the type of person I am and what I expect from the project. This will help you gauge the likelihood of us having conflicting personalities. And, it will highlight any differences in perspectives sooner -- if all goes as intended.
If it does look like we have a miss-match at the person level, I would like to take a moment and say one thing. It is okay -- we do not all think alike. You will face no hard feelings from me and I have no problem with you forking the code. If you do, I wish you the best of luck. And, do not feel like you cannot contact me and show me you weird and wonderful concoction.
If it does look like we have a miss-match at the person level, I would like to take a moment and say one thing. It is okay -- we do not all think alike. You will face no hard feelings from me and I have no problem with you forking the code. If you do, I wish you the best of luck. And, do not feel like you cannot contact me and show me your weird and wonderful concoction.
Now back to the project stuff...
@ -22,19 +26,19 @@ From my point-of-view, I am not in a rush to turn Console.Waterworks into a jack
Before moving on, I would like to reiterate a point from above. You will not receive any ill-will from me if our goals do not align. It is okay to disagree. I am well aware one persons "done" is another person’s starting point.
## "I don't want to read this, I want to ask a quick question"
### "I don't want to read this, I want to ask a quick question"
The easiest and faster way to contact me is via email. Which is [craig@craigoates.net](craig@craigoates.net, "Craig's email address"). I do not recommend filling an issue because of this.
## "What Should I Know Before I Get Started?"
### "What Should I Know Before I Get Started?"
Before you jump in, I recommend you read [The Complete Guide to Console.Waterworks](https://github.com/craigoates, "C.W. Complete Guide"). Console.Waterworks is not the most expansive or complex piece of code on the planet. But, it does have its own quirks and behaviours. I have tried to make it as modular and as easy to read as possible. But, it still has a reasonable amount of complexity to it. So, please read the guide.
## "How Can I Contribute?"
### "How Can I Contribute?"
You can contribute to the project in several ways. The obvious two ways are [filing issues](https://github.com/CraigOates/Console.Waterworks/issues/new, "C.W. Issues") and sending [pull requests](https://github.com/CraigOates/Console.Waterworks/compare, "C.W. Pull request"). You can, also, contribute by sending me an email. Although, the last one is not as open as the previous two. It is still an effective route to take if you want to discuss something at length. My email address is [craig@craigoates.net](craig@craigoates.net, "Craig's email address").
### Reporting Bugs
#### Reporting Bugs
I track bugs using [GitHub Issues](https://github.com/CraigOates/Console.Waterworks/issues/new, "C.W. Issues"). If you find one, fill out the template provided and file an issue.
@ -42,11 +46,11 @@ I track bugs using [GitHub Issues](https://github.com/CraigOates/Console.Waterwo
When you file a bug report, do not hold back with the details. The more information I have, the chance of me fixing it increases.
### Suggesting Enhancements
#### Suggesting Enhancements
You might have read [The Creator's Expectations](https://github.com/CraigOates/Console.Waterworks/blob/develop/CONTRIBUTING.md#the-creators-expectations-for-consolewaterworks, "Creator's Expections Section") above... If you have, you will know I hold a conservative attitude for adding features. With that said, I am not against adding new features -- stated above as well. If you believe your suggestion has some merit, please feel free to submit it. I am more than happy to discuss your plan. Please, do not feel offended if your suggestion does not get added to the project, though. That is not my intension.
### "How do I Submit an Enhancement Suggestion?"
#### "How do I Submit an Enhancement Suggestion?"
You can submit an enhancement suggestion via [GitHub Issues](https://github.com/CraigOates/Console.Waterworks/issues/new, "C.W. Issues"). Before you do, here is a list of things to consider when submitting an enhancement suggestion.
@ -63,7 +67,7 @@ You can submit an enhancement suggestion via [GitHub Issues](https://github.com/
I have decided not to include a template here because writing proposals can be a messy and tricky affair. They can be the rally call to the great unknown or a meticulous path to paradise. Each approach has its place in this world and I aim to keep it that way. With that said, try to keep your suggestion as clear and concise as possible. I ask this because -- to be frank -- if I do not understand your suggestion how can I agree to include it?
### Pull Requests
#### Pull Requests
Before submitting a pull request, I must stress the importance of talking to me first. I do not want you spending hours of your time writing code for Console.Waterworks to then face rejection. Your time is not my time and I would like to avoid wasting either of ours if I can help it. If there is something you would like to add to Console.Waterworks, you can do two things. The first is [email me](craig@craigoates.net, "Craig's email address") and talk about your plans. This is the quickest way for you to find out if your idea is worth pursuing. The second thing you can do is send an [enhancement suggestion](https://github.com/CraigOates/Console.Waterworks/issues/new, "C.W. Issues") via GitHub Issues and hold the discussion there. This will result in a slower response but the conversation will be in the open. If you decide to file a suggestion, make sure you have read "Suggesting Enhancements", above.
@ -77,11 +81,11 @@ Here is a list of things to consider when submitting a pull request:
- Follow the C# and Code Comments style guides.
- Describe how you intend to add the code into the project's documentation.
## Style Guides
### Style Guides
As the title of this section implies, the following pertains to a collection of guides and not rules. With that said, I ask you to adhere to them as best as you can. Doing so, you will make my life easier. It will, also, mean you will have a faster response from me -- less work for me to work through. If you feel like you need to break away from these guides, please do so with care and caution.
### Git Commit Messages
#### Git Commit Messages
- Limit the first line to 72 charters or less.
- Reference issues and pull requests after the first line.
@ -91,7 +95,7 @@ As the title of this section implies, the following pertains to a collection of
- Aim to keep the message list-like until the end. From there, include any extra information in standard prose.
- Try to keep everything as clear and concise as possible.
### C# (C-Sharp)
#### C# (C-Sharp)
Aim to adhere to the standard C# coding conventions. If you are working in Visual Studio, the automatic formatting should suffice.
@ -100,9 +104,9 @@ I have tried to reduce the inclusion of comments to public facing and "messy" co
If you would like to contribute to the project, thank you. Before you do, though, please make sure no one has already provided what you are offering. I am yet to come across someone with a liking for processing repeated issues, points or mistakes. And, I doubt I ever will, so please check. I appreciate all efforts by those checking to see if what they are saying is something new. On top of that, rejecting fifty individual issues is better than rejecting fifty of the same one. Well... that is my position of that anyway.
If you would like to contribute to the project, thank you. Before you do, though, please make sure no one has already provided what you are offering. I am yet to come across someone with a liking for processing repeated issues, points or mistakes. And, I doubt I ever will, so please check. I appreciate all efforts by those checking to see if what they are saying is something new.
Do not feel put-off if I am slow to respond. I will read what you have to say but I am not at my desk all the time. On top of that, I encourage you to refrain from instant replies if you can help it. This allows me to consider what you have said without feeling pressured. I do not want to waste your time by retracting a hasty and ill-thought-through response.
Filling out the template is required. Any pull request which does not include enough information to be reviewed in a timely manner may be closed at the maintainers' discretion.
Note: Filling out the template is required. Any pull request which does not include enough information to be reviewed in a timely manner may be closed at the maintainers' discretion.
## Description of the Change
### Description of the Change
[TO DELETE] Aim to be as clear and concise as possible here. Use illustrations and gifs if you believe it will help explain your point.
## Significant Design Changes
### Significant Design Changes
[TO DELETE] If your pull request alters the design of the code in a significant manner, please state here what the changes are. If the changes are minor, feel free you include them in the description above. Do statement there is no major changes, though, for clarity.
## Benefits
### Benefits
[TO DELETE] List out the benefits. Aim to keep them short and to the point.
## Possible (Immediate) Drawbacks
### Possible (Immediate) Drawbacks
[TO DELETE] List out any drawbacks your pull request introduces to the project. If you feel is necessary, elaborate as much as you can to help explain the drawbacks with accepting the pull request.
## Foreseen Issues
### Foreseen Issues
[TO DELETE] If you can foresee a problem **beyond** this pull request, use this section to highlight them. This will help determine the steps beyond the pull request, if any need to be taken.
Console.Waterworks is a Nuget package. It aim is to help you write extendable and command-based console programs in C# and .Net.
One of the main struggles with writing software is the need to write "plumbing code". It is the code which does not solve the main problem but it is necessary for us to reach a solution. This is why we all feel frustrated when we need to write it. It feels like we are going the long way round to that dream holiday in the sun. This is why I created Console.Waterworks. I believe we should face frustration when it finds us and only then. Why go looking for it?
@ -7,28 +11,38 @@ Amongst other things, Console.Waterworks has this one very handy trick. It allow
Do not panic if none of what I just said made no sense. I threw a lot of information at you in a short span of time. It is okay and not unexpected. Because of this, I have prepared several images showing Console.Waterworks in action. Please feel free to check it out. It should help explain what Console.Waterwork is and how it works.
## Disclaimer
### Disclaimer
Console.Waterworks is based on the [ConsoleApplicationBase](https://github.com/TypecastException/ConsoleApplicationBase, "ConsoleApplicationBase GitHub Repository") repository by [TypecastException](https://github.com/TypecastException, "TypecastException's GitHub Profile").
## Pre-Requisites
### Pre-Requisites
To use Console.Waterworks, I recommend you meet the following pre-requisites:
- You have experience with [C#](https://docs.microsoft.com/en-us/dotnet/csharp/, "C# Documentation").
- You can create a [.Net console program](http://www.com, "Console program tutorial") in [Visual Studio 2017](https://www.visualstudio.com/vs/, "Visual Studio 2017 Info.") or [Visual Studio Code](https://code.visualstudio.com/, "Visual Studio Code Info.").
- You can create a [.Net console program](http://www.com, "Console program tutorial") in [Visual Studio 2017](https://www.visualstudio.com/vs/, "Visual Studio 2017 Info.").
- You have experience with [Nuget](https://www.nuget.org/, "Nuget's website").
- You have Microsoft [.Net Framework 4.7](https://docs.microsoft.com/en-us/dotnet/framework/install/guide-for-developers, ".Net Framework download") or higher.
## Quick Start - Wiring Console.Waterworks in to your Console Program
### Quick Start - Wiring Console.Waterworks in to your Console Program
Before continuing... I am skipping the part about creating a .Net console program. This is because I assume you know how to do that. I am, also, assuming you are using Visual Studio 2017 and C# (not VB or F#).
@ -69,11 +83,11 @@ public string Test()
9 Add more methods to you console program.
## Guides
### Guides
There are several guides for Console.Waterworks and in various forms. I am hopeful you will find at least one of them helpful.
### Offline
#### Offline
I have created two guides for offline usage:
@ -82,7 +96,7 @@ I have created two guides for offline usage:
Both of these guides are printer friendly. And, they are best consumed on your favourite reading chair.
### Online
#### Online
For those sitting at their computer and connected to the world-wide web, there is a Wiki:
@ -90,19 +104,19 @@ For those sitting at their computer and connected to the world-wide web, there i
This guide aims to be a concise as possible. It assumes you are sitting at your desk and wanting the quick answer -- not the full answer.
## Code of Conduct
### Code of Conduct
Please visit the Code of Conduct page for Console.Waterworks at,
- [Code of Conduct page](https://github.com/CraigOates/Console.Waterworks/blob/master/CODE_OF_CONDUCT.md, "Code of Conduct page")
## Contributing to the Console.Waterworks Repository
### Contributing to the Console.Waterworks Repository
Please visit the Contributing page for Console.Waterworks at,
