diff --git a/.github/PULL_REQUEST_TEMPLATE.adoc b/.github/PULL_REQUEST_TEMPLATE.adoc new file mode 100644 index 00000000..e5b8ce8a --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.adoc @@ -0,0 +1,31 @@ +==== What is this PR About? + +Brief explanation of the guide or document changes you have made and/or +the new content you are contributing. + +==== How should we test or review this PR? + +Include any information or commands (please use code blocks) to help +reviewers understand and verify your contribution. + +==== Is there a relevant Trello card or Github issue open for this? + +Provide a link to any open Github issues or Trello cards that describe +the use case or problem you are solving. + +==== Who would you like to review this? + +cc: @redhat-cop/cant-contain-this + +''''' + +* [ ] Have you followed the +https://github.com/redhat-cop/uncontained.io/blob/master/CONTRIBUTING.md[contributing +guidelines]? +* [ ] Have you explained what your changes do, and why they add value to +the uncontained.io guides? + +''''' + +*Please note: we may close your PR without comment if you do not check +the boxes above and provide ALL requested information.* diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index 63c5be26..00000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,20 +0,0 @@ -#### What is this PR About? -Brief explanation of the guide or document changes you have made and/or the new content you are contributing. - -#### How should we test or review this PR? -Include any information or commands (please use code blocks) to help reviewers understand and verify your contribution. - -#### Is there a relevant Trello card or Github issue open for this? -Provide a link to any open Github issues or Trello cards that describe the use case or problem you are solving. - -#### Who would you like to review this? -cc: @redhat-cop/cant-contain-this - ------ - -- [ ] Have you followed the [contributing guidelines](https://github.com/redhat-cop/uncontained.io/blob/master/CONTRIBUTING.md)? -- [ ] Have you explained what your changes do, and why they add value to the uncontained.io guides? - ------ - -**Please note: we may close your PR without comment if you do not check the boxes above and provide ALL requested information.** diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 00000000..bbff37b4 --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,76 @@ += Contributor Covenant Code of Conduct + +== Our Pledge + +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 + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual +attention or advances +* Trolling, insulting/derogatory comments, and personal or political +attacks +* Public or private harassment +* 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 + +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 + +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 + +Instances of abusive, harassing, or otherwise unacceptable behavior may +be reported by contacting the project team at container-cop@redhat.com. +All complaints will be reviewed and investigated and will result in a +response that is deemed necessary and 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 + +This Code of Conduct is adapted from the +https://www.contributor-covenant.org[Contributor Covenant], version 1.4, +available at +https://www.contributor-covenant.org/version/1/4/code-of-conduct.html diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index b4f1e743..00000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,72 +0,0 @@ -# Contributor Covenant Code of Conduct - -## Our Pledge - -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 - -Examples of behavior that contributes to creating a positive environment include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or - advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* 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 - -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 - -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 - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at . All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and 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 - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html - -[homepage]: https://www.contributor-covenant.org diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 00000000..a2062454 --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,241 @@ += Contributing to Uncontained.io + +Thanks for checking out the uncontained.io guides! We’re excited to hear +and learn from you. Your experiences will benefit others who read and +use these guides. + +We’ve put together the following guidelines to help you figure out where +you can best be helpful. + +== Table of Contents + +1. link:#types-of-contributions-were-looking-for[Types of contributions +we’re looking for] +2. link:#ground-rules--expectations[Ground rules & expectations] +3. link:#how-to-contribute[How to contribute] +4. link:#style-guide[Style guide] +5. link:#setting-up-your-environment[Setting up your environment] +6. link:#contribution-review-process[Contribution review process] +7. link:#community[Community] + +== Types of contributions we’re looking for + +This project is an attempt at establish and document some guiding +principles and, dare we say it, best practices in the open source +emerging technology space. Currently that space, as we see it, is +predominantly made up of technologies that enable DevOps practices, such +as ``Cloud'' (API-automated Infrastructure), CI/CD tooling, container +technologies, microservices frameworks, and probably more. This project +was started by a community of thought leaders from Red Hat so if it +initially appears as if this site is only about Red Hat technologies, +it’s not intended to be, its just impassioned people writing about what +they know. + +There are also many ways you can directly contribute to the guides (in +descending order of need): + +* Fix editorial inconsistencies, inaccuracies, or stale content +* Add tutorials, examples, or anecdotes that help illustrate a point +* Revise language to be more approachable and friendly +* Propose a new guide (link:./docs/new_guides.adoc[here’s how]) + +Interested in making a contribution? Read on! + +== Ground rules & expectations + +Before we get started, here are a few things we expect from you (and +that you should expect from others): + +* Be kind and thoughtful in your conversations around this project. We +all come from different backgrounds and projects, which means we likely +have different perspectives on ``how open source is done.'' Try to +listen to others rather than convince them that your way is correct. +* Uncontained.io guides are released with a +link:./CODE_OF_CONDUCT.adoc[Contributor Code of Conduct]. By participating +in this project, you agree to abide by its terms. +* If you open a pull request, please ensure that your contribution +passes all tests. If there are test failures, you will need to address +them before we can merge your contribution. +* When adding content, please consider if it is widely valuable. Please +don’t add references or links to things you or your employer have +created as others will do so if they appreciate it. + +== How to contribute + +If you’d like to contribute, start by searching through the GitHub +https://github.com/redhat-cop/uncontained.io/issues[issues] and +https://github.com/redhat-cop/uncontained.io/pulls[pull requests] to see +whether someone else has raised a similar idea or question. + +If you don’t see your idea listed, and you think it fits into the goals +of this guide, do one of the following: * *If your contribution is +minor,* such as a typo fix, open a pull request. * *If your contribution +is major,* such as a new article or category, start by opening an issue +first. That way, other people can weigh in on the discussion before you +do any work. + +=== Contributing a new article + +See our guide on link:./docs/new_articles.adoc[contributing new content]. + +=== Migrating Content from OpenShift-Playbooks + +This site is the evolution of the +https://github.com/redhat-cop/openshift-playbooks[Openshift Playbooks] +site. + +Migrating content from there to here is fairly straightforward, but +involves some work. + +1. A migration script can be used to translate documents from the +https://github.com/redhat-cop/openshift-playbooks[openshift-playbooks] +repo. ++ +Usage: `./migrate-doc.sh [path/playbook-doc] [path/uncontained-doc]` ++ +Example: +`./migrate-doc.sh continuous_delivery/external-jenkins-integration.adoc articles/external-jenkins-integration.adoc` +2. Next, start the test site using the +link:#containerized-hugo-environment-quickstart-guide[container image] +or link:#native-hugo-environment-quickstart-guide[native hugo]. +3. Navigate to the content you migrated and ensure that: + +* all content renders correctly +* there are no broken links (we recommend using a link checker like +https://addons.mozilla.org/en-US/firefox/addon/linkchecker/[this one for +Firefox] or +https://chrome.google.com/webstore/detail/broken-link-checker/nibppfobembgfmejpjaaeocbogeonhch?hl=en[this +one for Chrome]) +* if the guide or article links to other guides, or articles, we suggest +you migrate those as well. + +1. Examine front matter. Ensure `title` is reader friendly, and that +the `date` represents the date written, not the date migrated. + +=== Helping us with Site Styling, User Experience, etc. + +The styling for the site is contained within a +https://gohugo.io/themes/[Hugo Theme]. The source code for the theme is +located in this repo at ./site/themes/uncontained.io. + +Specifically, the code for our HTML Layouts can be found in +./site/themes/uncontained.io/layouts/. The CSS code can be found in +link:./site/themes/uncontained.io/src/scss/[./site/themes/uncontained.io/src/scss]. + +See link:#building-and-developing-the-site[Building and Developing the +site] for instructions on how to perform local testing of changes. + +== Style guide + +This site is written in asciidoc format and is built using +https://asciidoctor.org/[Asciidoctor]. If you’re writing content, see +the link:./docs/style_guide.adoc[style guide] to help your prose match +the rest of the Guides. + +== Setting up your environment + +This site is powered by https://gohugo.io/[Hugo]. Running it on your +local machine only requires a working +https://gohugo.io/getting-started/installing[Hugo] installation, either +natively or a docker container. We recommend using the docker container +method (for obvious reasons) instead of your native operating system, +but you may choose either environment setup. + +=== Building and Developing the Site + +Uncontained.io uses the https://gohugo.io/[Hugo static site generator] +to translate Asciidoc into an HTML site. We wrap this functionality in +https://gulpjs.com/[Gulp] to streamline the build and test process. +Running the site requires https://nodejs.org/[Node.js]. Once installed, +you should have all you need to build, test and develop. To get started, +set up your local environment. + +.... +git clone https://github.com/redhat-cop/uncontained.io.git +cd uncontained.io/ +npm install +.... + +Our Hugo + Gulp setup is based on the +https://github.com/netlify/victor-hugo[victor-hugo] boilerplate. + +==== Run the Live Preview + +The live preview provides an embedded server in which you can test the +site locally, and watch changes being made as you develop. + +.... +npm start +.... + +or, if you’d like to also include _draft_ content like +`hugo server --buildDrafts --buildFuture`: + +.... +npm run start-preview +.... + +You should be able to view the site by browsing to +http://localhost:3000/. + +==== Build the Site + +The site build will simple generate all of the site html, css, +javascript, etc. This is the process we use to build and publish the +site. + +.... +npm run build +.... + +==== Deploying to OpenShift + +Uncontained.io is built and hosted on OpenShift, and deployed using +https://github.com/redhat-cop/openshift-applier[OpenShift Applier] + +Run the following to pull in applier: + +.... +ansible-galaxy install -r requirements.yml -p galaxy +.... + +Log into your _Prod_ OpenShift cluster, and run the following command. +`$ oc login ... $ ansible-playbook -i .applier-prod/ galaxy/openshift-applier/playbooks/openshift-cluster-seed.yml` +One of the things that was created by ansible is a `ServiceAccount` that +will be used for promoting your app from _Dev_ to _Prod_. We’ll need to +extract its credentials so that our pipeline can use that account. +`$ TOKEN=$(oc serviceaccounts get-token promoter -n field-guides-prod)` +We need to create the the _prod-api-credentials_ param file so our +pipeline will be able to verify a successful deployment to production. +`$ echo "TOKEN=${TOKEN} API_URL= REGISTRY_URL= SECRET_NAME=other-cluster-credentials" > .openshift/params/prod-cluster-credentials` + +Now, deploy your pipeline and dev environment to your _development_ +cluster: + +.... +oc login +ansible-playbook -i .applier/ galaxy/openshift-applier/playbooks/openshift-cluster-seed.yml +.... + +== Contribution review process + +This repo is currently maintained by @jaredburck, @etsauer, and +@sabre1041, who have commit access. They will likely review your +contribution. If you haven’t heard from anyone in 10 days, feel free to +bump the thread or @-mention a maintainer or +`@redhat-cop/cant-contain-this` to review your contribution. + +== Community + +Discussions about uncontained.io takes place within this repository’s +https://github.com/redhat-cop/uncontained.io/issues[Issues] and +https://github.com/redhat-cop/uncontained.io/pulls[Pull Requests] +sections and Trello’s +https://trello.com/b/JMaxIjCy/cant-contain-this[Cant-Contain-This] +board. Red Hatter’s can also find us on RocketChat’s #cant-contain-this +channel. Anybody is welcome to join these conversations. There is also a +http://uncontained.io/[mailing list] for regular updates. + +Wherever possible, do not take these conversations to private channels, +including contacting the maintainers directly. Keeping communication +public means everybody can benefit and learn from the conversation. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 4ed4f1d7..00000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,169 +0,0 @@ -# Contributing to Uncontained.io - -Thanks for checking out the uncontained.io guides! We're excited to hear and learn from you. Your experiences will benefit others who read and use these guides. - -We've put together the following guidelines to help you figure out where you can best be helpful. - -## Table of Contents - -0. [Types of contributions we're looking for](#types-of-contributions-were-looking-for) -0. [Ground rules & expectations](#ground-rules--expectations) -0. [How to contribute](#how-to-contribute) -0. [Style guide](#style-guide) -0. [Setting up your environment](#setting-up-your-environment) -0. [Contribution review process](#contribution-review-process) -0. [Community](#community) - -## Types of contributions we're looking for -This project is an attempt at establish and document some guiding principles and, dare we say it, best practices in the open source emerging technology space. Currently that space, as we see it, is predominantly made up of technologies that enable DevOps practices, such as "Cloud" (API-automated Infrastructure), CI/CD tooling, container technologies, microservices frameworks, and probably more. This project was started by a community of thought leaders from Red Hat so if it initially appears as if this site is only about Red Hat technologies, it's not intended to be, its just impassioned people writing about what they know. - -There are also many ways you can directly contribute to the guides (in descending order of need): - -* Fix editorial inconsistencies, inaccuracies, or stale content -* Add tutorials, examples, or anecdotes that help illustrate a point -* Revise language to be more approachable and friendly -* Propose a new guide ([here's how](./docs/new_guides.md)) - -Interested in making a contribution? Read on! - -## Ground rules & expectations - -Before we get started, here are a few things we expect from you (and that you should expect from others): - -* Be kind and thoughtful in your conversations around this project. We all come from different backgrounds and projects, which means we likely have different perspectives on "how open source is done." Try to listen to others rather than convince them that your way is correct. -* Uncontained.io guides are released with a [Contributor Code of Conduct](./CODE_OF_CONDUCT.md). By participating in this project, you agree to abide by its terms. -* If you open a pull request, please ensure that your contribution passes all tests. If there are test failures, you will need to address them before we can merge your contribution. -* When adding content, please consider if it is widely valuable. Please don't add references or links to things you or your employer have created as others will do so if they appreciate it. - -## How to contribute - -If you'd like to contribute, start by searching through the GitHub [issues](https://github.com/redhat-cop/uncontained.io/issues) and [pull requests](https://github.com/redhat-cop/uncontained.io/pulls) to see whether someone else has raised a similar idea or question. - -If you don't see your idea listed, and you think it fits into the goals of this guide, do one of the following: -* **If your contribution is minor,** such as a typo fix, open a pull request. -* **If your contribution is major,** such as a new article or category, start by opening an issue first. That way, other people can weigh in on the discussion before you do any work. - -### Contributing a new article - -See our guide on [contributing new content](./docs/new_articles.md). - -### Migrating Content from OpenShift-Playbooks - -This site is the evolution of the [Openshift Playbooks](https://github.com/redhat-cop/openshift-playbooks) site. - -Migrating content from there to here is fairly straightforward, but involves some work. - -1. A migration script can be used to translate documents from the [openshift-playbooks](https://github.com/redhat-cop/openshift-playbooks) repo. - - Usage: - ``` - ./migrate-doc.sh [path/playbook-doc] [path/uncontained-doc] - ``` - - Example: - ``` - ./migrate-doc.sh continuous_delivery/external-jenkins-integration.adoc articles/external-jenkins-integration.adoc - ``` -2. Next, start the test site using the [container image](#containerized-hugo-environment-quickstart-guide) or [native hugo](#native-hugo-environment-quickstart-guide). -3. Navigate to the content you migrated and ensure that: - * all content renders correctly - * there are no broken links (we recommend using a link checker like [this one for Firefox](https://addons.mozilla.org/en-US/firefox/addon/linkchecker/) or [this one for Chrome](https://chrome.google.com/webstore/detail/broken-link-checker/nibppfobembgfmejpjaaeocbogeonhch?hl=en)) - * if the guide or article links to other guides, or articles, we suggest you migrate those as well. -4. Examine front matter. Ensure `title` is reader friendly, and that the `date` represents the date written, not the date migrated. - -### Helping us with Site Styling, User Experience, etc. - -The styling for the site is contained within a [Hugo Theme](https://gohugo.io/themes/). The source code for the theme is located in this repo at [./site/themes/uncontained.io](./site/themes/uncontained.io). - -Specifically, the code for our HTML Layouts can be found in [./site/themes/uncontained.io/layouts/](./site/themes/uncontained.io/layouts/). The CSS code can be found in [./site/themes/uncontained.io/src/scss](./site/themes/uncontained.io/src/scss/). - -See [Building and Developing the site](#building-and-developing-the-site) for instructions on how to perform local testing of changes. - -## Style guide - -This site is written in asciidoc format and is built using [Asciidoctor](https://asciidoctor.org/). If you're writing content, see the [style guide](./docs/style_guide.adoc) to help your prose match the rest of the Guides. - -## Setting up your environment - -This site is powered by [Hugo](https://gohugo.io/). Running it on your local machine only requires a working [Hugo](https://gohugo.io/getting-started/installing) installation, either natively or a docker container. We recommend using the docker container method (for obvious reasons) instead of your native operating system, but you may choose either environment setup. - -### Building and Developing the Site - -Uncontained.io uses the [Hugo static site generator](https://gohugo.io/) to translate Asciidoc into an HTML site. We wrap this functionality in [Gulp](https://gulpjs.com/) to streamline the build and test process. Running the site requires [Node.js](https://nodejs.org/). Once installed, you should have all you need to build, test and develop. To get started, set up your local environment. - -``` -git clone https://github.com/redhat-cop/uncontained.io.git -cd uncontained.io/ -npm install -``` - -Our Hugo + Gulp setup is based on the [victor-hugo](https://github.com/netlify/victor-hugo) boilerplate. - -#### Run the Live Preview - -The live preview provides an embedded server in which you can test the site locally, and watch changes being made as you develop. - -``` -npm start -``` - -or, if you'd like to also include _draft_ content like `hugo server --buildDrafts --buildFuture`: - -``` -npm run start-preview -``` - -You should be able to view the site by browsing to http://localhost:3000/. - -#### Build the Site - -The site build will simple generate all of the site html, css, javascript, etc. This is the process we use to build and publish the site. - -``` -npm run build -``` - -#### Deploying to OpenShift - -Uncontained.io is built and hosted on OpenShift, and deployed using [OpenShift Applier](https://github.com/redhat-cop/openshift-applier) - -Run the following to pull in applier: - -``` -ansible-galaxy install -r requirements.yml -p galaxy -``` - -Log into your _Prod_ OpenShift cluster, and run the following command. - ``` - $ oc login - ... - $ ansible-playbook -i .applier-prod/ galaxy/openshift-applier/playbooks/openshift-cluster-seed.yml - ``` -One of the things that was created by ansible is a `ServiceAccount` that will be used for promoting your app from _Dev_ to _Prod_. We'll need to extract its credentials so that our pipeline can use that account. - ``` - $ TOKEN=$(oc serviceaccounts get-token promoter -n field-guides-prod) - ``` -We need to create the the *prod-api-credentials* param file so our pipeline will be able to verify a successful deployment to production. - ``` - $ echo "TOKEN=${TOKEN} - API_URL= - REGISTRY_URL= - SECRET_NAME=other-cluster-credentials" > .openshift/params/prod-cluster-credentials - ``` - -Now, deploy your pipeline and dev environment to your _development_ cluster: - -``` -oc login -ansible-playbook -i .applier/ galaxy/openshift-applier/playbooks/openshift-cluster-seed.yml -``` - -## Contribution review process - -This repo is currently maintained by @jaredburck, @etsauer, and @sabre1041, who have commit access. They will likely review your contribution. If you haven't heard from anyone in 10 days, feel free to bump the thread or @-mention a maintainer or `@redhat-cop/cant-contain-this` to review your contribution. - -## Community - -Discussions about uncontained.io takes place within this repository's [Issues](https://github.com/redhat-cop/uncontained.io/issues) and [Pull Requests](https://github.com/redhat-cop/uncontained.io/pulls) sections and Trello's [Cant-Contain-This](https://trello.com/b/JMaxIjCy/cant-contain-this) board. Red Hatter's can also find us on RocketChat's #cant-contain-this channel. Anybody is welcome to join these conversations. There is also a [mailing list](http://uncontained.io/) for regular updates. - -Wherever possible, do not take these conversations to private channels, including contacting the maintainers directly. Keeping communication public means everybody can benefit and learn from the conversation. diff --git a/README.adoc b/README.adoc new file mode 100644 index 00000000..150d95e9 --- /dev/null +++ b/README.adoc @@ -0,0 +1,71 @@ += uncontained.io + +https://travis-ci.org/redhat-cop/uncontained.io[image:https://travis-ci.org/redhat-cop/uncontained.io.svg?branch=master[Build +Status]] + +This is the source code repository for +http://uncontained.io/[Uncontained.io], a site that focuses on +Containers, Cloud, and Digital Transformation guidance for the +Enterprise. + +== Background + +The first sets of uncontained.io guides were created and curated by Red +Hat Consultants, along with input from outside community reviewers, but +they are not exclusive to Red Hat products. + +Our goal is to aggregate community best practices, _not_ what Red Hat +(or any other individual or entity) thinks is best. Therefore, we try to +use examples and quotations from the field or others to illustrate our +points. + +*Uncontained.io is a community resource.* One reason we started this +project is because we felt that there weren’t enough really good +resources for organizations creating and using DevOps-centric tooling & +tech. We made these guides open source in hopes that you’ll use this +space to talk about best practices, then document them when you’ve found +consensus. We’d like this to be a safe space to talk about what’s hard, +what’s scary, and what’s simply confusing about running and using +containers & cloud technologies. + +== Roadmap + +We’ve shared our vision and priorities for this project in our +link:docs/roadmap.adoc[roadmap]. + +== Contributing + +This site is powered by https://gohugo.io/[Hugo]. Our goal is for this +project to reflect community best practices, so we’d love your input! +Got a question or an idea? Check out our +link:/CONTRIBUTING.adoc[contributing guidelines] for ways to offer +feedback and contribute. + +== Licenses + +Content is released under +https://creativecommons.org/licenses/by-sa/4.0/[CC-BY-SA-4.0]. See +link:notices.adoc[notices] for complete details, including attribution +guidelines, contribution terms, and software and third-party licenses +and permissions. + +https://creativecommons.org/licenses/by-sa/4.0/[image:https://i.creativecommons.org/l/by-sa/4.0/88x31.png[creativecommons]] + +== Acknowledgments + +The working group for the initial release of uncontained.io consisted of +*@jaredburck, @etsauer, @sabre1041, @rdebeasi, @lwrigh, @oybed*, and +*Phyllis Fann*. + +Thanks to our contributors for lending their valuable input and +expertise leading up to the initial release, to *@drew* and *@mattw* for +coming up with the new site name, Abby Gardner for brand design, and +*@lwrigh* and *@rdebeasi* for UX design. And to Red Hat brand, +marketing, legal, and anyone missed, thank you for your time and effort +to help the uncontained.io project. + +== Disclaimer + +While we’ve got advice about running containers and open source +technologies, we are not lawyers. Be sure to read our +link:notices.adoc#legal-disclaimer[disclaimer] before diving in. diff --git a/README.md b/README.md deleted file mode 100644 index dbfad229..00000000 --- a/README.md +++ /dev/null @@ -1,35 +0,0 @@ -# uncontained.io - -[![Build Status](https://travis-ci.org/redhat-cop/uncontained.io.svg?branch=master)](https://travis-ci.org/redhat-cop/uncontained.io) - -This is the source code repository for [Uncontained.io](http://uncontained.io/), a site that focuses on Containers, Cloud, and Digital Transformation guidance for the Enterprise. - -## Background -The first sets of uncontained.io guides were created and curated by Red Hat Consultants, along with input from outside community reviewers, but they are not exclusive to Red Hat products. - -Our goal is to aggregate community best practices, *not* what Red Hat (or any other individual or entity) thinks is best. Therefore, we try to use examples and quotations from the field or others to illustrate our points. - -**Uncontained.io is a community resource.** One reason we started this project is because we felt that there weren't enough really good resources for organizations creating and using DevOps-centric tooling & tech. We made these guides open source in hopes that you'll use this space to talk about best practices, then document them when you've found consensus. We'd like this to be a safe space to talk about what's hard, what's scary, and what's simply confusing about running and using containers & cloud technologies. - -## Roadmap - -We've shared our vision and priorities for this project in our [roadmap](docs/roadmap.md). - -## Contributing - -This site is powered by [Hugo](https://gohugo.io/). Our goal is for this project to reflect community best practices, so we'd love your input! Got a question or an idea? Check out our [contributing guidelines](/CONTRIBUTING.md) for ways to offer feedback and contribute. - -## Licenses - -Content is released under [CC-BY-SA-4.0](https://creativecommons.org/licenses/by-sa/4.0/). See [notices](notices.md) for complete details, including attribution guidelines, contribution terms, and software and third-party licenses and permissions. - -[![creativecommons](https://i.creativecommons.org/l/by-sa/4.0/88x31.png)](https://creativecommons.org/licenses/by-sa/4.0/) - -## Acknowledgments - -The working group for the initial release of uncontained.io consisted of **@jaredburck, @etsauer, @sabre1041, @rdebeasi, @lwrigh, @oybed**, and **Phyllis Fann**. - -Thanks to our contributors for lending their valuable input and expertise leading up to the initial release, to **@drew** and **@mattw** for coming up with the new site name, Abby Gardner for brand design, and **@lwrigh** and **@rdebeasi** for UX design. And to Red Hat brand, marketing, legal, and anyone missed, thank you for your time and effort to help the uncontained.io project. - -## Disclaimer -While we've got advice about running containers and open source technologies, we are not lawyers. Be sure to read our [disclaimer](notices.md#legal-disclaimer) before diving in. diff --git a/docs/content_model.adoc b/docs/content_model.adoc new file mode 100644 index 00000000..f2be95fe --- /dev/null +++ b/docs/content_model.adoc @@ -0,0 +1,106 @@ += Content Model + +Uncontained.io guides help individuals, communities, and companies +embrace open source software. It explains not only how to accomplish a +task, but why you’d want to, and how that task fits into a larger story +of organizations undergoing a digital transformation. + +This content was originally created and curated by Red Hat’s PaaS +Community of Practice, and covers topics that are very relevant to Red +Hat users, but it is not specific to Red Hat products. + +Everything written on uncontained.io should fall into one of the +following categories. + +== Articles + +Simply put, an _article_ is any single piece of content. - A `title` - A +`date` - An `author` (or authors) - A `category` (see below for Category +options) - Optionally: - One or more `tags` - One or more `collections` +that the article is a part of + +While meant to be read from beginning to end, articles have a table of +contents to help the reader quickly skim the content and find a relevant +subsection. + +=== Implementation Guides + +_Implementation guides_ are long form articles that provide an approach +to solving an organizational problem using technology. These articles +may have multiple contributors, contain visuals and anecdotes to +illustrate their point and may provide opinionated guidance. + +=== Add-Ons + +An _add-on_ article (a.k.a an Appendix) is a piece of content that is +associated with another article, but would have broken up the flow or +the primary content or otherwise makes more sense to live separately. +Typically, an add-on should start by stating the assumption that the +reader first reads and understands the originating article before +getting into the meat of the content. + +=== Tutorials + +A tutorial is a walk-through using commands and code that are used to +teach a concept. + +=== Deep Dives (a.k.a Funamentals Guides) + +A _deep dive_ or _fundamentals guide_ will cover a specific topic area +in order to provide some fundamental base knowledge that will be needed +or assumed in other implementation guides (for example, ``Getting +Started with Containers''). + +== Collections + +A _collection_ is an entirely different content format, intended to +provide a way of grouping together multiple articles in a way that +provides a more wholistic message. We are still in development of the +_collections_ model right now, and will post more soon. + +== Design Elements + +If you’re writing an article or tutorial guide, here are some smaller +design elements that enrich the content experience. We use them to draw +the reader’s attention and break up walls of text; therefore, they +should all get some sort of visual treatment. + +=== Pull quote + +We use quotes in the guide to illustrate a point through an anecdote. +Pull quotes should highlight real people and their experiences. + +=== Image + +Images help visually illustrate a point. Some images are instructive, +such as a graph. Other images are visual, such as a webpage screenshot. +We should have lots of these. + +=== Data vignette + +Whereas pull quotes and images help ground ideas in something specific +and concrete, data vignettes help connect ideas to bigger systems. + +Data vignettes are limited so as not to overwhelm, but contain just +enough information to help readers understand why they should pay +attention to a certain idea. + +=== Historical vignette + +Historical vignettes are fun anecdotes that keep a reader’s attention. +They make community members the heroes of the story, and help pass down +cultural knowledge. + +=== Content taxonomy tags + +Content taxonomy tags are categories or classifications (a term or +phrase) that is added to a web publication that relates the specific +publication to other contents that are similarly tagged. + +=== Tag clouds + +A tag cloud (word cloud, or weighted list in visual design) is a visual +representation of text data, typically used to depict keyword metadata +(tags) on websites, or to visualize free form text. Tags are usually +single words, and the importance of each tag is shown with font size or +color. diff --git a/docs/content_model.md b/docs/content_model.md deleted file mode 100644 index 07055acb..00000000 --- a/docs/content_model.md +++ /dev/null @@ -1,69 +0,0 @@ -# Content Model -Uncontained.io guides help individuals, communities, and companies embrace open source software. It explains not only how to accomplish a task, but why you'd want to, and how that task fits into a larger story of organizations undergoing a digital transformation. - -This content was originally created and curated by Red Hat's PaaS Community of Practice, and covers topics that are very relevant to Red Hat users, but it is not specific to Red Hat products. - -Everything written on uncontained.io should fall into one of the following categories. - -## Articles - -Simply put, an _article_ is any single piece of content. -- A `title` -- A `date` -- An `author` (or authors) -- A `category` (see below for Category options) -- Optionally: - - One or more `tags` - - One or more `collections` that the article is a part of - -While meant to be read from beginning to end, articles have a table of contents to help the reader quickly skim the content and find a relevant subsection. - -### Implementation Guides - -_Implementation guides_ are long form articles that provide an approach to solving an organizational problem using technology. These articles may have multiple contributors, contain visuals and anecdotes to illustrate their point and may provide opinionated guidance. - -### Add-Ons - -An _add-on_ article (a.k.a an Appendix) is a piece of content that is associated with another article, but would have broken up the flow or the primary content or otherwise makes more sense to live separately. Typically, an add-on should start by stating the assumption that the reader first reads and understands the originating article before getting into the meat of the content. - -### Tutorials - -A tutorial is a walk-through using commands and code that are used to teach a concept. - -### Deep Dives (a.k.a Funamentals Guides) - -A _deep dive_ or _fundamentals guide_ will cover a specific topic area in order to provide some fundamental base knowledge that will be needed or assumed in other implementation guides (for example, "Getting Started with Containers"). - -## Collections - -A _collection_ is an entirely different content format, intended to provide a way of grouping together multiple articles in a way that provides a more wholistic message. We are still in development of the _collections_ model right now, and will post more soon. - -## Design Elements - -If you're writing an article or tutorial guide, here are some smaller design elements that enrich the content experience. We use them to draw the reader's attention and break up walls of text; therefore, they should all get some sort of visual treatment. - -### Pull quote - -We use quotes in the guide to illustrate a point through an anecdote. Pull quotes should highlight real people and their experiences. - -### Image - -Images help visually illustrate a point. Some images are instructive, such as a graph. Other images are visual, such as a webpage screenshot. We should have lots of these. - -### Data vignette - -Whereas pull quotes and images help ground ideas in something specific and concrete, data vignettes help connect ideas to bigger systems. - -Data vignettes are limited so as not to overwhelm, but contain just enough information to help readers understand why they should pay attention to a certain idea. - -### Historical vignette - -Historical vignettes are fun anecdotes that keep a reader's attention. They make community members the heroes of the story, and help pass down cultural knowledge. - -### Content taxonomy tags - -Content taxonomy tags are categories or classifications (a term or phrase) that is added to a web publication that relates the specific publication to other contents that are similarly tagged. - -### Tag clouds - -A tag cloud (word cloud, or weighted list in visual design) is a visual representation of text data, typically used to depict keyword metadata (tags) on websites, or to visualize free form text. Tags are usually single words, and the importance of each tag is shown with font size or color. diff --git a/docs/new_articles.adoc b/docs/new_articles.adoc new file mode 100644 index 00000000..885d4d1f --- /dev/null +++ b/docs/new_articles.adoc @@ -0,0 +1,58 @@ += Proposing a new articles + +Thanks for your interest in suggesting a new uncontained.io guide! Your +suggestions help us decide what to work on next. + +== If you’d like to propose a new articles + +1. *https://github.com/redhat-cop/uncontained.io/issues[Open an issue]* +with your suggestion. Please explain: + +* Why the topic is broadly useful to uncontained.io contributors +* Why it doesn’t fit into an existing guide +* 3-5 bullets of expected sub-topics + +1. We (likely @jaredburck, @etsauer, or @sabre1041) will label the +issue `new-guide` and share feedback. + +At this point, we may decide the topic doesn’t warrant a new guide and +close the issue, or we may recommend adding the information to an +existing guide. That’s okay! All suggestions are welcomed contributions, +because they help us understand what our community is thinking. + +== If you would like to work on a new article + +Start by cloning this repo. + +Create a new guide using `hugo`: + +.... +cd ./site/ +hugo new articles/my-new-article.adoc +.... + +From here, you can start to develop your content. Check out our +link:./content_model.adoc[contend model] and link:./style_guide.adoc[style +guide] for more guidance on writing and structuring your content. + +== Typical Workflow for New Content Creation + +* [ ] Label your issue `research` +* [ ] Collect existing community resources (links, blog posts, projects) +on your issue. Everybody is welcome to contribute. +** What else has been written on this topic? +** What projects do this well? +** Who might be people with valuable experience that we should talk to? +* [ ] Open a PR with an outline for the new guide. Anyone is welcome to +give feedback until we reach general consensus. +* [ ] Label your issue `in progress` +** [ ] Add the guide to our editorial schedule with estimated date for +1st draft completion +** [ ] Request assets from Design for illustrations, Twitter cards, and +anything else needed +* [ ] Label your issue `draft` and update PR with the 1st draft. Anyone +is welcome to give feedback. +* [ ] Make final edits and add estimated date for completion +* [ ] Release the new guide! 🎉 +* [ ] Promote new guide in weekly email digest and monthly public call +for the Containers & PaaS Community of Practice! 🎉 diff --git a/docs/new_articles.md b/docs/new_articles.md deleted file mode 100644 index aa4e3cb5..00000000 --- a/docs/new_articles.md +++ /dev/null @@ -1,42 +0,0 @@ -# Proposing a new articles - -Thanks for your interest in suggesting a new uncontained.io guide! Your suggestions help us decide what to work on next. - -## If you'd like to propose a new articles - -1. **[Open an issue](https://github.com/redhat-cop/uncontained.io/issues)** with your suggestion. Please explain: - * Why the topic is broadly useful to uncontained.io contributors - * Why it doesn't fit into an existing guide - * 3-5 bullets of expected sub-topics -2. We (likely @jaredburck, @etsauer, or @sabre1041) will label the issue ```new-guide``` and share feedback. - -At this point, we may decide the topic doesn't warrant a new guide and close the issue, or we may recommend adding the information to an existing guide. That's okay! All suggestions are welcomed contributions, because they help us understand what our community is thinking. - -## If you would like to work on a new article - -Start by cloning this repo. - -Create a new guide using `hugo`: - -``` -cd ./site/ -hugo new articles/my-new-article.adoc -``` - -From here, you can start to develop your content. Check out our [contend model](./content_model.md) and [style guide](./style_guide.md) for more guidance on writing and structuring your content. - -## Typical Workflow for New Content Creation - -- [ ] Label your issue ```research``` -- [ ] Collect existing community resources (links, blog posts, projects) on your issue. Everybody is welcome to contribute. - * What else has been written on this topic? - * What projects do this well? - * Who might be people with valuable experience that we should talk to? -- [ ] Open a PR with an outline for the new guide. Anyone is welcome to give feedback until we reach general consensus. -- [ ] Label your issue ```in progress``` - - [ ] Add the guide to our editorial schedule with estimated date for 1st draft completion - - [ ] Request assets from Design for illustrations, Twitter cards, and anything else needed -- [ ] Label your issue ```draft``` and update PR with the 1st draft. Anyone is welcome to give feedback. -- [ ] Make final edits and add estimated date for completion -- [ ] Release the new guide! 🎉 -- [ ] Promote new guide in weekly email digest and monthly public call for the Containers & PaaS Community of Practice! 🎉 diff --git a/docs/personas.md b/docs/personas.adoc similarity index 61% rename from docs/personas.md rename to docs/personas.adoc index ef34b9e5..d56e9991 100644 --- a/docs/personas.md +++ b/docs/personas.adoc @@ -1,111 +1,130 @@ -# Personas += Personas -## 1. Community Contributor +== 1. Community Contributor -### Characteristics +=== Characteristics -* Moderately to expertly experienced with containers and related technologies -* Feels some sense of ownership over the idea ("I want to share this with the world") +* Moderately to expertly experienced with containers and related +technologies +* Feels some sense of ownership over the idea (``I want to share this +with the world'') * Sees self as a mentor, teacher, director, or leader * Still building community reputation * May have never contributed content or a guide before * May have no ninja points or would like to join and become a ninja -### Primary Goals +=== Primary Goals * Wants to share their knowledge of containers with the world * Wants people to actually use these guides and give feedback * Wants to give back or become a thought leader -### Frustrations/Pain Points +=== Frustrations/Pain Points * May not know how or where to begin to contribute * May not know what to work on or is needed -## 2. Core Contributor +== 2. Core Contributor -### Characteristics +=== Characteristics * Expertly experienced with containers and related technologies -* Feels a sense of ownership over the idea ("I want to share this with the world") +* Feels a sense of ownership over the idea (``I want to share this with +the world'') * Sees self as a thought leader, mentor, and teacher * Has a decent community reputation -* Has contributed open sourced a project before. May contribute multiple projects -* Likely authors blog posts and other thought leadership content on container technologies +* Has contributed open sourced a project before. May contribute multiple +projects +* Likely authors blog posts and other thought leadership content on +container technologies * May have ninja points or looking to advance in ninja belt color -### Primary Goals +=== Primary Goals * Wants to share their knowledge of containers with the world * Wants people to actually use these guides and give feedback * Wants to give back by sharing their expertise and thought leadership -### Frustrations/Pain Points +=== Frustrations/Pain Points * Feeling burned out, exhausted from open source work -## 3. Community Reviewer +== 3. Community Reviewer -### Characteristics +=== Characteristics * Experienced with containers and related technologies -* Wants to share ownership of the project ("I want to build this with others") +* Wants to share ownership of the project (``I want to build this with +others'') * Sees community, not self, as the ultimate decision maker * Has a decent audience/reputation * Has open sourced personal projects before * Likely manages projects on their own time (volunteer work) -### Primary Goals +=== Primary Goals * Get people to participate, contribute back to the project -* Make sure everybody involved with the project is happy and has a good experience +* Make sure everybody involved with the project is happy and has a good +experience -### Frustrations/Pain Points +=== Frustrations/Pain Points -* Managing a community is exhausting, especially when it's volunteer work +* Managing a community is exhausting, especially when it’s volunteer +work -## 4. Core Reviewer +== 4. Core Reviewer -### Characteristics +=== Characteristics * Experienced with containers and related technologies -* Wants to share ownership of the project ("I want to build this with others") +* Wants to share ownership of the project (``I want to build this with +others'') * Sees community, not self, as ultimate decision maker * Has a decent audience/reputation * Has open sourced personal projects before * Likely manages projects on their own time (volunteer work) -### Primary Goals +=== Primary Goals * Get people to participate, contribute back to the project -* Make sure everybody involved with the project is happy and has a good experience +* Make sure everybody involved with the project is happy and has a good +experience -### Frustrations/Pain Points +=== Frustrations/Pain Points -* Managing a community is exhausting, especially when it's volunteer work +* Managing a community is exhausting, especially when it’s volunteer +work -## 5. Red Hat Corporate employees +== 5. Red Hat Corporate employees -### Characteristics +=== Characteristics -* Teams of employees working at Red Hat, primarily consulting, and includes multiple other business units across the organization, such as engineering, support, marketing, and sales -* Likely feels some sense of ownership over the project ("We are open sourcing this project to the community") +* Teams of employees working at Red Hat, primarily consulting, and +includes multiple other business units across the organization, such as +engineering, support, marketing, and sales +* Likely feels some sense of ownership over the project (``We are open +sourcing this project to the community'') * Company plays a supporting role only with no decision making powers * Based on the open source software practices and policies -* Projects are managed by paid employees on their own time as volunteer work -* Cares about fostering a healthy community, and wants to share ownership in a formal capacity +* Projects are managed by paid employees on their own time as volunteer +work +* Cares about fostering a healthy community, and wants to share +ownership in a formal capacity -### Primary Goals +=== Primary Goals * Improve brand and reputation - * Attract new technical talent for recruiting (make sure people hear about it) +** Attract new technical talent for recruiting (make sure people hear +about it) * Grow a platform (get people to use it) * Get people to participate, contribute back to the project -* Make sure everybody involved with the project is happy and has a good experience +* Make sure everybody involved with the project is happy and has a good +experience -### Frustrations/Pain Points +=== Frustrations/Pain Points * Balancing community + supporting corporate needs - * (For community: being a good corporate citizen, respecting cultural norms) - * (For corporate: adhering to company policies) +** (For community: being a good corporate citizen, respecting cultural +norms) +** (For corporate: adhering to company policies) * Making sure people know about the project diff --git a/docs/roadmap.adoc b/docs/roadmap.adoc new file mode 100644 index 00000000..ece66c05 --- /dev/null +++ b/docs/roadmap.adoc @@ -0,0 +1,77 @@ += Roadmap + +Our vision for uncontained.io guides is to provide a jumping off point +for individuals, communities, and companies to sustainably embrace +containers and related container technologies as well as industry best +practices. + +=== CY 2017 + +We started by focusing on open source containers, because they play a +critical role in growing healthy cloud projects. Creators help set good +examples for contributors and consumers of container technologies. We +also noticed there were very few good comprehensive resources aimed at +helping creators and consumers to effectively utilize containers. + +* [x] Create a first set of guides that help creators start and use +their own open source containers +* [x] Make the guides public and release it as an open source project +* [x] Expand https://github.com/redhat-cop/CONTRIBUTING.adoc[Contributing +to uncontained.io on GitHub] to include community best practices for +contributors. +* [ ] Foster healthy community dynamics so the guides become a place to +codify community best practices + +=== Q1 2018 + +We’ll improve upon existing content and start to focus on additional +content for open source consumers and contributors. + +* [ ] Continue to improve the content for adopting and utilizing +containers +* [ ] Improve guide discoverability for the container technologies +guides +* [ ] Expand the uncontained.io guides to include content for container +technologies + +This is our current plan. As with most everything in the uncontained.io +project, it is open to community feedback. + +=== Q2 2018 + +We’ll improve upon existing content and start to focus on additional +content for open source consumers and contributors. + +* [ ] Continue to improve the content for containers +* [ ] Improve guide discoverability for containers +* [ ] Expand the uncontained.io guides to include content for other +container technologies + +This is our current plan. As with most everything in the uncontained.io +project, it is open to community feedback. + +=== Q3 2018 + +We’ll improve upon existing content and start to focus on additional +content for open source consumers and contributors. + +* [ ] Continue to improve the content for containers +* [ ] Improve guide discoverability for containers +* [ ] Expand the uncontained.io guides to include content for other +container technologies + +This is our current plan. As with most everything in the uncontained.io +project, it is open to community feedback. + +=== Q4 2018 + +We’ll improve upon existing content and start to focus on additional +content for open source consumers and contributors. + +* [ ] Continue to improve the content for containers +* [ ] Improve guide discoverability for containers +* [ ] Expand the uncontained.io guides to include content for other +container technologies + +This is our current plan. As with most everything in the uncontained.io +project, it is open to community feedback. diff --git a/docs/roadmap.md b/docs/roadmap.md deleted file mode 100644 index 480f93a1..00000000 --- a/docs/roadmap.md +++ /dev/null @@ -1,52 +0,0 @@ -# Roadmap - -Our vision for uncontained.io guides is to provide a jumping off point for individuals, communities, and companies to sustainably embrace containers and related container technologies as well as industry best practices. - -### CY 2017 - -We started by focusing on open source containers, because they play a critical role in growing healthy cloud projects. Creators help set good examples for contributors and consumers of container technologies. We also noticed there were very few good comprehensive resources aimed at helping creators and consumers to effectively utilize containers. - -* [x] Create a first set of guides that help creators start and use their own open source containers -* [x] Make the guides public and release it as an open source project -* [x] Expand [Contributing to uncontained.io on GitHub](https://github.com/redhat-cop/CONTRIBUTING.md) to include community best practices for contributors. -* [ ] Foster healthy community dynamics so the guides become a place to codify community best practices - -### Q1 2018 - -We'll improve upon existing content and start to focus on additional content for open source consumers and contributors. - -* [ ] Continue to improve the content for adopting and utilizing containers -* [ ] Improve guide discoverability for the container technologies guides -* [ ] Expand the uncontained.io guides to include content for container technologies - -This is our current plan. As with most everything in the uncontained.io project, it is open to community feedback. - -### Q2 2018 - -We'll improve upon existing content and start to focus on additional content for open source consumers and contributors. - -* [ ] Continue to improve the content for containers -* [ ] Improve guide discoverability for containers -* [ ] Expand the uncontained.io guides to include content for other container technologies - -This is our current plan. As with most everything in the uncontained.io project, it is open to community feedback. - -### Q3 2018 - -We'll improve upon existing content and start to focus on additional content for open source consumers and contributors. - -* [ ] Continue to improve the content for containers -* [ ] Improve guide discoverability for containers -* [ ] Expand the uncontained.io guides to include content for other container technologies - -This is our current plan. As with most everything in the uncontained.io project, it is open to community feedback. - -### Q4 2018 - -We'll improve upon existing content and start to focus on additional content for open source consumers and contributors. - -* [ ] Continue to improve the content for containers -* [ ] Improve guide discoverability for containers -* [ ] Expand the uncontained.io guides to include content for other container technologies - -This is our current plan. As with most everything in the uncontained.io project, it is open to community feedback. diff --git a/docs/style_guide.adoc b/docs/style_guide.adoc index 6df4a39e..7e9bbc87 100644 --- a/docs/style_guide.adoc +++ b/docs/style_guide.adoc @@ -8,7 +8,7 @@ toc::[] > > In other words, the way we write is just as important as the way we design. Consider these things when writing copy. -_Reference: link:https://github.com/github/opensource.guide/blob/master/docs/styleguide.md[opensource.guide style guide]_ +_Reference: link:https://github.com/github/opensource.guide/blob/master/docs/styleguide.adoc[opensource.guide style guide]_ This document provides content writer's with some guidance around how to structure new content contributions. We hope it is a valuable resource for you. @@ -126,7 +126,7 @@ All written content should follow these principles: Content should maintain a light-hearted, but wise (think classy, not overly excited) tone. Open source is fun! Readers should feel inspired, not discouraged, by the tone of your writing, and they should trust you to help them along their journey. -Reference: link:https://github.com/github/opensource.guide/blob/master/docs/styleguide.md#content-principles[opensource.guide style guide] +Reference: link:https://github.com/github/opensource.guide/blob/master/docs/styleguide.adoc#content-principles[opensource.guide style guide] == Mentions @@ -140,7 +140,7 @@ When referring to a project on GitHub, link to the repository so others can dive - :smile: @JaredBurck took a similar approach to link:https://github.com/datproject/dat[Dat]... - :cry: @JaredBurck took a similar approach to Dat... -Reference: link:https://github.com/github/opensource.guide/blob/master/docs/styleguide.md#mentions[opensource.guide style guide] +Reference: link:https://github.com/github/opensource.guide/blob/master/docs/styleguide.adoc#mentions[opensource.guide style guide] == Capitalization @@ -157,4 +157,4 @@ The word "guides" is not capitalized when referring to the "uncontained.io guide - :smile: The guide is meant to.. - :cry: The goal of this Guide is to... -Reference: link:https://github.com/github/opensource.guide/blob/master/docs/styleguide.md#capitalization[opensource.guide style guide] +Reference: link:https://github.com/github/opensource.guide/blob/master/docs/styleguide.adoc#capitalization[opensource.guide style guide] diff --git a/notices.adoc b/notices.adoc new file mode 100644 index 00000000..08a2d9d0 --- /dev/null +++ b/notices.adoc @@ -0,0 +1,59 @@ +== Legal Disclaimer + +Red Hat is not a law firm. As such, Red Hat does not provide legal +advice. The material in these guides does not constitute legal advice +nor does contributing to the guides or communicating with Red Hat or +other contributors about the guides create an attorney-client +relationship. + +Uncontained.io guides are made available and contributed to under +licenses that include terms that, for the protection of contributors, +make clear that the projects are offered ``as-is'', without warranty, +and disclaiming liability for damages resulting from using the projects. +This guide is no different. The open content license it is offered under +https://creativecommons.org/licenses/by-sa/4.0/legalcode#s5[includes +such terms]. + +Running the open source uncontained.io project, like any human endeavor, +involves uncertainty and trade-offs. We hope these guide help, but they +may include mistakes, and can’t address every situation. If you have any +questions about the uncontained.io project, we encourage you to do your +own research, seek out experts, and discuss with our community. If you +have any legal questions, you should consult with your own legal counsel +before moving forward. + +== Licenses + +Content is copyright © uncontained.io authors, released under +https://creativecommons.org/licenses/by-sa/4.0/[CC-BY-SA-4.0], which +gives you permission to use content for almost any purpose (but does not +grant you any trademark permissions), so long as you note the license +and give credit, such as follows: + +_________________________________________________________________________________________________________________________________________________________________________________________ +Content based on +https://github.com/redhat-cop/uncontained.io[github.com/redhat-cop/uncontained.io] +used under the +https://creativecommons.org/licenses/by-sa/4.0/[CC-BY-SA-4.0] license. +_________________________________________________________________________________________________________________________________________________________________________________________ + +Code, including source files and code samples if any in the content, is +released under http://www.apache.org/licenses/LICENSE-2.0[Apache-2.0], +with the following exceptions: + +* none at this time + +This means you can use the code and content in this repository except +for Red Hat trademarks in your own projects. When using the Red Hat +logos, be sure to follow the http://brand.redhat.com/logos/[Red Hat logo +guidelines]. + +When you contribute to this repository you are doing so under the above +licenses. + +https://creativecommons.org/licenses/by-sa/4.0/[image:https://i.creativecommons.org/l/by-sa/4.0/88x31.png[creativecommons]] + +== Permissions + +Screenshots and images from other projects are used with permissions +below. diff --git a/notices.md b/notices.md deleted file mode 100644 index 42c811b9..00000000 --- a/notices.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -layout: article-alt -title: Legal Disclaimer and Notices ---- - -## Legal Disclaimer - -Red Hat is not a law firm. As such, Red Hat does not provide legal advice. The material in these guides does not constitute legal advice nor does contributing to the guides or communicating with Red Hat or other contributors about the guides create an attorney-client relationship. - -Uncontained.io guides are made available and contributed to under licenses that include terms that, for the protection of contributors, make clear that the projects are offered "as-is", without warranty, and disclaiming liability for damages resulting from using the projects. This guide is no different. The open content license it is offered under [includes such terms](https://creativecommons.org/licenses/by-sa/4.0/legalcode#s5). - -Running the open source uncontained.io project, like any human endeavor, involves uncertainty and trade-offs. We hope these guide help, but they may include mistakes, and can't address every situation. If you have any questions about the uncontained.io project, we encourage you to do your own research, seek out experts, and discuss with our community. If you have any legal questions, you should consult with your own legal counsel before moving forward. - -## Licenses - -Content is copyright © uncontained.io authors, released under [CC-BY-SA-4.0](https://creativecommons.org/licenses/by-sa/4.0/), which gives you permission to use content for almost any purpose (but does not grant you any trademark permissions), so long as you note the license and give credit, such as follows: - -> Content based on [github.com/redhat-cop/uncontained.io](https://github.com/redhat-cop/uncontained.io) used under the [CC-BY-SA-4.0](https://creativecommons.org/licenses/by-sa/4.0/) license. - -Code, including source files and code samples if any in the content, is released under [Apache-2.0](http://www.apache.org/licenses/LICENSE-2.0), with the following exceptions: - -* none at this time - -This means you can use the code and content in this repository except for Red Hat trademarks in your own projects. When using the Red Hat logos, be sure to follow the [Red Hat logo guidelines](http://brand.redhat.com/logos/). - -When you contribute to this repository you are doing so under the above licenses. - -[![creativecommons](https://i.creativecommons.org/l/by-sa/4.0/88x31.png)](https://creativecommons.org/licenses/by-sa/4.0/) - -## Permissions - -Screenshots and images from other projects are used with permissions below. diff --git a/site/content/_index.adoc b/site/content/_index.adoc new file mode 100644 index 00000000..ee31d326 --- /dev/null +++ b/site/content/_index.adoc @@ -0,0 +1,4 @@ +________________________________________________________________________________________________________ +Minimalism is not a lack of something. It’s simply the perfect amount of +something. — Nicholas Burroughs +________________________________________________________________________________________________________ diff --git a/site/content/_index.md b/site/content/_index.md deleted file mode 100644 index 5394c5b6..00000000 --- a/site/content/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Home ---- -> Minimalism is not a lack of something. It’s simply the perfect amount of something. -> — Nicholas Burroughs diff --git a/site/content/authors/_index.adoc b/site/content/authors/_index.adoc new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/site/content/authors/_index.adoc @@ -0,0 +1 @@ + diff --git a/site/content/authors/_index.md b/site/content/authors/_index.md deleted file mode 100644 index c19d421b..00000000 --- a/site/content/authors/_index.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: Authors ---- diff --git a/site/content/tags/config/_index.adoc b/site/content/tags/config/_index.adoc new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/site/content/tags/config/_index.adoc @@ -0,0 +1 @@ + diff --git a/site/content/tags/config/_index.md b/site/content/tags/config/_index.md deleted file mode 100644 index 460f7639..00000000 --- a/site/content/tags/config/_index.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: Configuration ---- diff --git a/site/content/tags/og/_index.adoc b/site/content/tags/og/_index.adoc new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/site/content/tags/og/_index.adoc @@ -0,0 +1 @@ + diff --git a/site/content/tags/og/_index.md b/site/content/tags/og/_index.md deleted file mode 100644 index 292c1e85..00000000 --- a/site/content/tags/og/_index.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: Opengraph ---- diff --git a/site/themes/uncontained.io/LICENSE.adoc b/site/themes/uncontained.io/LICENSE.adoc new file mode 100644 index 00000000..a9237f21 --- /dev/null +++ b/site/themes/uncontained.io/LICENSE.adoc @@ -0,0 +1,22 @@ +The MIT License (MIT) + +Copyright (c) 2016-2018 Red Hat, Inc. and Vimux + +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. diff --git a/site/themes/uncontained.io/LICENSE.md b/site/themes/uncontained.io/LICENSE.md deleted file mode 100644 index 6ae1e340..00000000 --- a/site/themes/uncontained.io/LICENSE.md +++ /dev/null @@ -1,20 +0,0 @@ -The MIT License (MIT) - -Copyright (c) 2016-2018 Red Hat, Inc. and Vimux - -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. diff --git a/site/themes/uncontained.io/README.adoc b/site/themes/uncontained.io/README.adoc new file mode 100644 index 00000000..54ba5cd4 --- /dev/null +++ b/site/themes/uncontained.io/README.adoc @@ -0,0 +1,68 @@ += Uncontained.io theme + +Based on the http://themes.gohugo.io/theme/blank/[Blank starter theme] + +== Developing + +Follow the instructions in +https://github.com/redhat-cop/uncontained.io/blob/master/CONTRIBUTING.adoc#setting-up-your-environment[setting +up your environment] to get up and running with Hugo and the tools we +use to build uncontained.io. + +In the root of this repository, run `hugo serve -D --noHTTPCache` to +start the Hugo server. + +Then, go to `themes/uncontained.io` and run these commands: + +.... +npm install +npm start +.... + +Now, when you edit a file in `src`, the following will happen: + +1. Gulp will see that a file has changed +2. Gulp will compile the source files and output the results to +`static/dist` +3. Hugo will see that files in `static` have changed +4. Hugo will auto-reload the page in your browser. + +== Building + +To build the site: + +.... +cd themes/uncontained.io +npm run build +cd ../.. +hugo +.... + +== CSS Framework + +We are using a pared-down version of https://getbootstrap.com/[Bootstrap +4], customized as per the +https://getbootstrap.com/docs/4.0/getting-started/theming/[theming +instructions]. We’ve left out parts of Bootstrap CSS and all of +Bootstrap JS. To see which Bootstrap modules we’re using, see +`style.scss`. To see all of the Bootstrap modules that exist, see +https://github.com/twbs/bootstrap/blob/v4-dev/scss/bootstrap.scss[bootstrap.scss]. + +== Sass/CSS Code Standards + +In lieu of formal code standards, here are some general guidelines: + +* Minimize selector specificity. +* Use simple, meaningful CSS class names. Use only lowercase letters and +dashes (no underscores, double dashes, etc.). +* Use variables for colors and font names. +* Prefer removing styles to overriding them. +* Prefer configuring the framework to overriding it. + +=== Resources + +* https://getbootstrap.com/docs/4.1/extend/approach/[Bootstrap - +Approach] +* http://markdotto.com/2012/03/02/stop-the-cascade/[Stop the Cascade] +* https://github.com/statnews/boilermaker/blob/master/sass.md[STAT’s +Sass/CSS style guide] diff --git a/site/themes/uncontained.io/README.md b/site/themes/uncontained.io/README.md deleted file mode 100644 index 15b44185..00000000 --- a/site/themes/uncontained.io/README.md +++ /dev/null @@ -1,52 +0,0 @@ -# Uncontained.io theme - -Based on the [Blank starter theme](http://themes.gohugo.io/theme/blank/) - -## Developing - -Follow the instructions in [setting up your environment](https://github.com/redhat-cop/uncontained.io/blob/master/CONTRIBUTING.md#setting-up-your-environment) to get up and running with Hugo and the tools we use to build uncontained.io. - -In the root of this repository, run `hugo serve -D --noHTTPCache` to start the Hugo server. - -Then, go to `themes/uncontained.io` and run these commands: -``` -npm install -npm start -``` - -Now, when you edit a file in `src`, the following will happen: - -1. Gulp will see that a file has changed -2. Gulp will compile the source files and output the results to `static/dist` -3. Hugo will see that files in `static` have changed -4. Hugo will auto-reload the page in your browser. - -## Building - -To build the site: -``` -cd themes/uncontained.io -npm run build -cd ../.. -hugo -``` - -## CSS Framework - -We are using a pared-down version of [Bootstrap 4](https://getbootstrap.com/), customized as per the [theming instructions](https://getbootstrap.com/docs/4.0/getting-started/theming/). We've left out parts of Bootstrap CSS and all of Bootstrap JS. To see which Bootstrap modules we're using, see `style.scss`. To see all of the Bootstrap modules that exist, see [bootstrap.scss](https://github.com/twbs/bootstrap/blob/v4-dev/scss/bootstrap.scss). - -## Sass/CSS Code Standards - -In lieu of formal code standards, here are some general guidelines: - -- Minimize selector specificity. -- Use simple, meaningful CSS class names. Use only lowercase letters and dashes (no underscores, double dashes, etc.). -- Use variables for colors and font names. -- Prefer removing styles to overriding them. -- Prefer configuring the framework to overriding it. - -### Resources - -- [Bootstrap - Approach](https://getbootstrap.com/docs/4.1/extend/approach/) -- [Stop the Cascade](http://markdotto.com/2012/03/02/stop-the-cascade/) -- [STAT's Sass/CSS style guide](https://github.com/statnews/boilermaker/blob/master/sass.md) diff --git a/site/themes/uncontained.io/archetypes/default.adoc b/site/themes/uncontained.io/archetypes/default.adoc new file mode 100644 index 00000000..703ca3c6 --- /dev/null +++ b/site/themes/uncontained.io/archetypes/default.adoc @@ -0,0 +1 @@ ++++ title = ``'' date = ``'' +++ diff --git a/site/themes/uncontained.io/archetypes/default.md b/site/themes/uncontained.io/archetypes/default.md deleted file mode 100644 index 03855e35..00000000 --- a/site/themes/uncontained.io/archetypes/default.md +++ /dev/null @@ -1,4 +0,0 @@ -+++ -title = "" -date = "" -+++ \ No newline at end of file diff --git a/site/themes/uncontained.io/layouts/partials/contribute.html b/site/themes/uncontained.io/layouts/partials/contribute.html index 77f6a1e5..4f3f4599 100644 --- a/site/themes/uncontained.io/layouts/partials/contribute.html +++ b/site/themes/uncontained.io/layouts/partials/contribute.html @@ -2,5 +2,5 @@

Contribute

Help us make uncontained.io even better! Our source code is available on GitHub.

We welcome issues and pull requests.

- Get Started + Get Started
diff --git a/site/themes/uncontained.io/theme.toml b/site/themes/uncontained.io/theme.toml index 4e0f882a..41b986af 100644 --- a/site/themes/uncontained.io/theme.toml +++ b/site/themes/uncontained.io/theme.toml @@ -1,6 +1,6 @@ name = "uncontained.io Theme" license = "MIT" -licenselink = "https://github.com/redhat-cop/uncontained.io/blob/master/themes/uncontained.io/LICENSE.md" +licenselink = "https://github.com/redhat-cop/uncontained.io/blob/master/themes/uncontained.io/LICENSE.adoc" description = "Hugo Theme for uncontained.io. Based on Blank theme by Vimux." homepage = "http://uncontained.io/" features = ["blog"]