update (#42)

doc/README.rst

@@ -0,0 +1,16 @@
+================================
+UXL Infrastructure Documentation
+================================
+
+Documentation related to infrastructure for UXL.
+
+`UXL GitHub`_
+    Managing GitHub repositories and organizations
+`UXL Slack`_
+    Managing Slack channels
+`Web Hosting`_
+    Hosting project web sites
+
+.. _`UXL GitHub`: uxl-github.rst
+.. _`UXL Slack`: uxl-slack.rst
+.. _`Web Hosting`: web-hosting.rst

doc/uxl-github.rst

@@ -0,0 +1,30 @@
+=================
+UXL use of GitHub
+=================
+
+This document describes the use of GitHub for the UXL project.
+
+uxlfoundation org
+=================
+
+The UXL project is hosted on GitHub under the `uxlfoundation`_ organization. It
+contains repos that are not specific to any one open source project. There will
+be a small set of ``owners`` for the org. ``@thelinuxfoundation`` is an owner
+as backup in case UXL owners are not available.
+
+Giving Access to Resources
+--------------------------
+
+Try to use GitHub Teams that are defined by roles. For example,
+``@oneapi-spec-maintainers`` are the maintainers for the oneapi spec and have
+write access. Using a team-based role instead of directly adding maintainers to
+the repo makes it possible to ``@tag`` the team in issues and PRs.
+
+If a role specific team is overkill, but you still want to be able to ``@tag``
+someone in a repo in uxlfoundation org, they can be added to the `UXL Members`_
+team. If you have a role in UXL (e.g. SIG leader), you can be added as a
+maintainer of this team.
+
+
+.. _`uxlfoundation`: https://github.com/uxlfoundation
+.. _`UXL Members`: https://github.com/orgs/uxlfoundation/teams/uxl-members

doc/uxl-slack.rst

@@ -0,0 +1,22 @@
+================
+UXL Use of Slack
+================
+
+This document describes the use of Slack for the UXL project.
+
+Channels
+========
+
+There are channels for each SIG (e.g. ``sig-math``), project (e.g. ``onemkl``), and working group (e.g. ``wg-open-source``). Channels are public unless there is a specific need (e.g. ``steering-committee``, ``security``).
+
+GitHub Integration
+==================
+
+It is possible for GitHub Actions to post messages in Slack. This can be useful for notifications of CI failures, new issues, etc. To enable this feature for a channel:
+
+* add `@GitHub Messages` to the channel
+* add a GitHub action to your repo. See `Slack Action`_ as an example.
+* add ``SLACK_BOT_TOKEN`` to the GitHub secrets for the repo. Get the value
+  from Robert Cohn
+
+.. _`Slack Action`: https://github.com/uxlfoundation/spec-working-group/blob/main/.github/workflows/slack-pr.yaml

doc/web-hosting.rst

@@ -0,0 +1,34 @@
+===========
+Web Hosting
+===========
+
+Projects typically need web sites for documentation and other information.
+
+Providers
+=========
+
+`GitHub Pages`_
+    GitHub pages is usually the best solution for web sites that are static
+    HTML. Many people know how to use it, and it is free. It is also easy to
+    set up and maintain. They recommend not using it for sites bigger than 1
+    Gbyte. You are only allowed static HTML, CSS, and JavaScript files. You
+    can use Jekyll to generate the site, but you cannot use server-side
+    languages like PHP. You can use client-side JavaScript to make the site
+    interactive. You can use a custom domain name, HTTPS, and a custom 404 page.
+
+.. _`GitHub Pages`: https://pages.github.com/
+
+Domain Names
+============
+
+Most providers make it easy to host a web site in their domain. For example, the oneapi spec uses GitHub pages and can be found at: https://uxlfoundation.github.io/oneAPI-spec/spec/. While this is fine for many projects, some projects may want to have their own domain name. Using your own domain name gives you more flexibility for future changes. For example, GitHub pages uses their `github.io` domain name, the org name, and the repo name. If any of that changes, you will need to update all the links and set up redirects. If you use your own domain name, you can change the hosting provider without changing the domain name.
+
+Web hosting providers, including GitHub pages, lets you use your own domain name. You can buy a domain name from a domain name registrar, and then set up the DNS to point to the hosting provider. While it is not hard or expensive to do this, you may want to use the uxlfoundation.org domain name:
+
+* Linux foundation owns and manages the uxlfoundation.org domain name.
+* Establishes the foundation as the owner of the project.
+
+For an example see the `UXL project site`_ which is hosted on GitHub pages but uses the uxlfoundation.org domain name. It is published from the `UXL project site repo`_.
+
+.. _`UXL project site`: https://uxlfoundation.org/
+.. _`UXL project site repo`: https://github.com/uxlfoundation/uxlfoundation.org