feat: more new content, updates to existing pages

Author: timclegg

_config.yml

@@ -43,7 +43,7 @@ header_pages:
   - publishing/working_with_repos.md
 header_links:
   -
-    img: assets/images/DevRel_Logo.png
+    img: /assets/images/DevRel_Logo.png
     img_alt: Oracle Developer Relations Logo
     url: /
     style: "width: 30px; height: 30px;"
@@ -52,7 +52,7 @@ header_links:
     url: https://developer.oracle.com
   - 
     title: Repositories
-    url: https://github.com/oracle-devrel
+    url: https://github.com/orgs/oracle-devrel/repositories
 
 minima:
   social_links:

_data/projects.yml

@@ -1,8 +1,8 @@
 - name: RedBull Honda Racing and Oracle Analytics Hands-on-Lab
   link: https://github.com/oracle-devrel/redbull-analytics-hol
   desc: Learn machine learning the fun way, with Oracle and RedBull Honda Racing.
-- name: Cloud Car
-  link: https://github.com/oracle-devrel/cloud-car
+- name: Eff Uno Racer
+  link: https://github.com/oracle-devrel/eff-uno-racer
   desc: Build an Oracle Cloud Infrastructure-controlled Raspberry Pi and Arduino powered open-wheel race car made with plastic bricks.
 - name: Using Open Policy Agent with OCI
   link: https://github.com/oracle-devrel/oci-pac-opa

home.html

@@ -15,7 +15,7 @@ <h2>Featured Projects</h2>
 </ul>
 
 <h2>Getting Started</h2>
-<p>Can't wait to get started? Check out our <a href="/publishing">publishing section</a> which will step you through how to get a repository, how to work with DevRel repositories, and more.</p>
+<p>Can't wait to get started? Check out our <a href="/publishing">publishing section</a> which will step you through how to get a repository, how to work with Oracle Developer Relations repositories, and more.</p>
 
 <h2>About Us</h2>
 <p>Curious who we are? Why are we doing what we're doing? Why is the sky blue? Well, we won't be answering the last question, but learn more about our team <a href="about">here</a>.</p>

publishing/expectations.md

@@ -14,4 +14,4 @@ Before diving into getting a DevRel repo, here's what we ask (and expect) of you
 * Ideally there should be two or more maintainers for each repo (project). One person can't do everything (particularly the required code reviews), so having at least two maintainers is a very good idea.
 
 <br><br>
-[< How to Publish](/publishing) \| [Getting a Repository >](/publishing/getting_a_repo)
+[< [Where to Publish](where_to_publish.md) \| [Getting a Repository >](/publishing/getting_a_repo)

publishing/getting_a_repo.md

@@ -4,6 +4,8 @@ title: Getting a Repository
 permalink: /publishing/getting_a_repo
 ---
 
+{% include toc.md %}
+
 # Getting a Repository
 
 The Developer Relations team strives to make getting a repository as easy and as fast as possible. While the process isn't perfect, it does allow you to quickly move forward.
@@ -24,8 +26,7 @@ Don't work at Oracle, but have a great idea that you'd like to collaborate with
 
 ## About Your New Repo
 
-The repo will come with public visibility, so there's nothing special to do to publish your work. You'll be set up as a maintainer (along with the other people you've requested as maintainers). From there, you're ready to [start working with your repo](working_with_repos.md).
-
+The repo will come with public visibility, so there's nothing special to do to publish your work. You'll be set up as a maintainer (along with the other people you've requested as maintainers). From there, you're ready to [start working with your repo](/working_with_our_repos).
 
 <br><br>
-[< Expectations](/publishing/expectations) \| [Working With Our Repositories >](/working_with_our_repos)
+[< [Standards](standards.md) \| [Working With Our Repositories >](/working_with_our_repos)

publishing/how_we_do_it.md

@@ -0,0 +1,31 @@
+---
+layout: page
+title: How We Do It
+permalink: /publishing/how_we_do_it
+---
+
+# Why Share?
+It's true that we don't need to be sharing the what/why/how of what we do, but we're big proponents for supporting the broader open-source community.  Who knows, maybe you'll find a useful nugget that might help you in your journey.  We hope so!
+
+# Useful GitHub Actions
+Here are the community-developed GitHub Actions that we use:
+
+* [mshick/add-pr-comment](https://github.com/mshick/add-pr-comment)
+
+  This is used pretty heavily to post comments to a PR.  Useful for providing feedback to the PR.
+
+* [cla-assistant/github-action](https://github.com/cla-assistant/github-action)
+
+  This is a terrific way of making sure folks agree to a Contributor License Agreement (CLA).  It's non-intrusive, easy-to-use/follow and very simple to deploy.
+
+* [SonarSource/sonarcloud-github-action](https://github.com/SonarSource/sonarcloud-github-action)
+
+  Pretty self-explanatory, but this is for SonarCloud.io automatic scanning.
+
+# Other Tools
+
+#### RepoLinter
+[RepoLinter](https://github.com/todogroup/repolinter) is totally awesome.  It allows for easy scanning of the repo and is *really* useful.  Unfortunately there's no officially-supported Docker image for it, so we built our own and published it privately to our GitHub Container Registry.  Not ideal, but we're not in the business of building/hosting RepoLinter containers, so decided this was probably best.  For some reason it didn't build out-of-the-box, but did after modifying `Dockerfile` a bit along with a `run_repolinter.sh` script.
+
+#### Scancode-Toolkit
+[Scancode-Toolkit](https://github.com/nexB/scancode-toolkit) is a terrific tool for detecting the license(s) used.  We use for this purpose.  Incidentally, it's another great tool that we had to build (and host, privately) the container for.  It would be great if there was a ready-to-go (officially supported) container, but none was available.  Certainly not capping on this project, as it's super useful... just deploying it was a bit more involved because of the lack of a publicly available "official" container.

publishing/index.md

@@ -6,9 +6,15 @@ permalink: /publishing
 
 # Before You Start
 
+* [Where to Publish](where_to_publish.md)
 * [What's Expected of You](expectations.md)
+* [Standards](standards.md)
 
 # Getting Started
 
 * [Getting a Repository](getting_a_repo.md)
 * [Working With Our Repositories](working_with_repos.md)
+
+# Extra Credit
+
+* [How We Do It](how_we_do_it.md)

publishing/standards.md

@@ -0,0 +1,44 @@
+---
+layout: page
+title: Standards
+permalink: /publishing/standards
+---
+
+# Repository Naming
+Although our repo names vary a bit, we do have a rhyme and reason with how we name repos.  Here goes!
+
+| Type of Content | Naming Standard | Notes |
+|-----------------|-----------------|-------|
+| Terraform Modules | `terraform-oci-<name>` | This format is needed for publishing to the [HashiCorp Terraform Module Registry](https://registry.terraform.io/browse/modules). |
+| DevO Content | `devo-<name>` | This is for text-based content that is going to DevO. |
+| Language-specific solution | `<language>-<name>` | To keep it somewhat organized, we try to group by language for many projects.  Names such as `go-hello-world`, `ruby-hello-world`, etc. are just a few ideas.  Clearly we're looking for more than `hello-world` projects, but you get the idea!  ;)
+| Tool | `<name>` | There are some projects that are tools.  While they *could* go under the language-specific definition above, they typically have a really cool name that we just don't feel right ruining with a language-specific prefix.  This is a bit subjective, but if there's a really cool name for something, we want to keep a good thing going! |
+
+# Required Repo Structure
+We try to focus on being flexible and easy-to-use.  There is a minimum set of files and structure that we do enforce (via Actions).  Rather than just surprise you, here's what we expect (at minimum):
+
+```
+.
+├── .github
+├── .gitignore
+├── LICENSE
+└── README.md
+```
+
+## .gitignore
+We expect the `.gitignore` file to ignore superfluous and extraneous "clutter" that's not necessary (things like hidden files that are not really needed, local caching files, etc.).  You'll likely need to adjust the `.github` file for the language(s) and framework(s) you'll be using in your project.  Customize away!
+
+# Branching
+We do not enforce a specific branching strategy, but leave it up to each project maintainer to dictate what's best for the project.  See [Working With Our Repos](/publishing/expectations) for more info.
+
+# Commit/PR Comments
+We prefer to standardize on using [ConventionalCommits](https://www.conventionalcommits.org/en/v1.0.0/) when generating change logs and creating comments on commits, PRs, etc.
+
+# Scanning of Source Code
+Most projects that contain source code (all but the text-only repos) are setup to be scanned by SonarCloud.io, along with a scanning status badge on the README.  Feel free to use (leave) this badge in-tact, as it's a nice marker to instill confidence in your code (or to encourage you to improve it).
+
+# Committing Code
+Do not commit directly to `main`.  It won't work anyway (`main` is protected).  Use Pull Requests (PRs) instead.  You can do this via a fork or branch.  If you're a maintainer, you can create a branch (you have permissions to do so).  If you're an outside contributor (or maintainer), you may fork the project (you don't have permissions to create a branch in the repo).  See [Working With Our Repos](/publishing/expectations) for more info.
+
+<br><br>
+[< [What's Expected of You](/publishing/expectations) \| [Getting a Repository >](/publishing/getting_a_repo)

publishing/where_to_publish.md

@@ -0,0 +1,20 @@
+---
+layout: page
+title: Where to Publish?
+permalink: /publishing/where_to_publish
+---
+
+We love content.  Really - we're crazy about *good* content!  Part of having lots of great content is making it accessible.  After all, if you can't find it, it doesn't do anyone any good!  To try to help keep our terrific content in-order, we have a couple of different options when it comes to publishing content.  This page is designed to help you figure out what's best for your specific use-case.
+
+Here's the "secret decoder ring" (of sorts) on where to publish:
+
+| Type of Content | Platform |
+|-----------------|----------|
+| Lab / Tutorial | [developer.oracle.com](https://developer.oracle.com) |
+| Source Code (sample, example, tool, etc.) | [Developer Relations GitHub Organization](https://github.com/oracle-devrel) |
+| Blog | [blogs.oracle.com/developers](https://blogs.oracle.com/developers/) |
+| Series of Articles | [developer.oracle.com](https://developer.oracle.com) |
+
+
+<br><br>
+[< Publishing](/publishing/) \| [What's Expected of You >](/publishing/expectations)

publishing/working_with_repos.md

@@ -25,6 +25,12 @@ We prefer to standardize on using [ConventionalCommits](https://www.conventional
 
 There are lots of branching strategies out there. We don't dictate how to use branches --- we leave this up to the project/repo maintainer(s) to decide how to use them. Each maintainer is able to select the branching strategy that they're most comfortable with.
 
+There are many different branching strategies (this list is by no means exhaustive):
+
+* [GitHub Flow](https://githubflow.github.io)
+* [git-flow](https://nvie.com/posts/a-successful-git-branching-model/)
+* [OneFlow](https://www.endoflineblog.com/oneflow-a-git-branching-model-and-workflow)
+
 # Automated Checks
 
 There are several checks which are setup by default. These checks must successfully pass before a merge can be made. Your repo will be set up to pass the checks.
@@ -35,12 +41,16 @@ Here's what's needed to pass:
 
 	You may use other licenses. However, until the project (repo) has been approved to use a non-pre-approved license, you will not be able to merge the PR (that's failing the license validation check).
 
-* Include the proper copyright notice on the **first line**
+* Include the proper copyright notice in the **first two lines**
 
 	Make sure that the following code is present: `Copyright (c) 2021 Oracle and/or its affiliates.`. It's also ok to use something like `Copyright (c) 2000-2021 Oracle and/or its affiliates.` (a range of years, instead of a single year). Both will pass just fine.
 
 	If this is missing, warnings will be raised and a comment made on the PR (notifying you of which file(s) are missing the copyright notice).
 
+* Check for required files
+
+  The `LICENSE`, `README.md` must be present.  These are provided as part of your repo (as it's provisioned). So long as they're not removed, there should be no issues.
+  
 * Block changes to protected files (see below).
 
 	There are several files/directories that should not be modified. One Action checks to make sure that none of these files are modified in a PR --- if they are, the PR fails (and posts a comment to the PR stating why it failed).