Skip to content

README-instructions.md

Latest commit

 

History

History
279 lines (176 loc) · 22.9 KB

README-instructions.md

File metadata and controls

279 lines (176 loc) · 22.9 KB
Raw

The AI Alliance banner

How to Use microsite-template

This repo is used as a template to create and publish AI Alliance “microsites”. It is setup as a GitHub template repo, which you can use to create a new repo. Even if you aren't creating a microsite, you can use this procedure to create a new AI Alliance repo for other purposes. Just delete the docs directory after creating the repo and skip the steps that don't apply to you.

See also GITHUB_PAGES.md, which has more advanced instructions for developers.

Creating Your Repo

These are the main steps, with details below:

Tip

If you choose not to do some of the steps now, for example publishing the GitHub pages website immediately (see step 8), create an Issue in the repo for each step to be done later, as a reminder.

  1. Create your repo from the this template repo.
  2. (Optional) Create a project (i.e., a dashboard) to track your work. Click the Project tab in the repo GitHub page and then either click the + New project+ button or if you want your project to join an existing dashboard, click the Link a project button and find the correct project. By default, project #39, Misc. Alliance Tasks, will be used in the next step.
  3. Convert placeholder template variables in many files to the correct values, using the finish-microsite.sh script. Run finish-microsite.sh --help for details or see the expanded description below.
    1. These local changes were pushed upstream by finish-microsite.sh, unless you used the --no-push argument. If so, push your local changes upstream when ready.
  4. Modify the "header buttons" in docs/_includes/header_buttons_custom.html to be what you want to appear at the top of each page. See the OTDI site for an example customization. Or if you don't want any buttons, delete the contents of that file (but don't delete the file...).
    1. Note that anchor tags with external links should include target="_blank", while internal links, like the link in the file to Join This Project don't use external targets.
  5. Add your initial custom content for the pages in the docs directory. Delete the files you don't use, e.g., second_page.markdown and the nested folder. (They are there to provide examples.)
  6. Add your initial custom content to the README.md.
  7. If you plan to publish the website from the latest branch, merge changes to that branch from main.
  8. Edit the content of AGENTS.md, a helper file for coding agents, and SECURITY.md, which defines the project security policy, as appropriate.
  9. Edit the repo's Settings.
    1. On the repo's home page in GitHub, click the Settings "gear" on the upper right-hand side.
    2. Scroll down to Features and click Discussions to enable them (unless you don't want them; in this case, remove the URL on the docs/contributing.markdown page!).
      1. Click the green Setup discussions button, then edit and submit the "welcome" message. (The default is usually fine.)
    3. Click the checkbox labeled Require contributors to sign off on web-based commits Loading. (Under the Commits part of the page, near the bottom.)
    4. On the left-hand side, click the link for Pages. Under Branch, select the main or latest branch depending on which one you want to use, then select the /docs directory. (NOTE: Make sure the repo is public or else the pages won't get published.) The public URL will be https://the-ai-alliance.github.io/REPO_NAME_MACRO
    5. On the left-hand side, click the link for Advanced Security. Enable all the alerts and security updates. For the Dependabot version updates, the configuration should already be correct (as defined in the included .github/dependabot.yml file), but you can change it by clicking the Configure button.
    6. Back on the General panel, configure the default branch if you don't want to use main. WARNING: The website, READMEs and other documentation often refer to main as the default branch. Change those references to the new branch name.
    7. Consider defining branch protection rules under the Branches panel. See other repos, like Tapestry, for examples.
    8. Under the Security and Quality panel, the SECURITY.md file already defines the security policy. Enable any or all of the quality and security checks shown on this panel.
  10. Add the website description and URL in the appropriate location on the Alliance GitHub organization README files and the Alliance GitHub website. (See Need Help? below...)
  11. Add any Python source files to src and test files src/tests. See the discussion below about common targets for code already supported by the Makefile and .common.mk, etc.
  12. Delete the files README-instructions.md, finish-microsite.sh, and any of the LICENSES/LICENSE.* files that don't apply to your project.
  13. Final steps: If you are using a separate publication branch, e.g., latest, don't forget to merge all changes from main to the publication branch and push both branches upstream, e.g., git push --all (when using the CLI in a terminal).

You should now have a published website!

Note

We are planning to automate as many of the manual steps as we can.

Let's look at these steps in more detail.

1. Create your repo from the microsite-template.

  1. Go to the microsite-template repo.
  2. Click the right hand-side green button Use this template and select Create a new repository.
  3. Select The-AI-Alliance as the owner account.
  4. Enter a unique name for the new repo. I'll use ai-for-evil-project as an example here.
  5. Enter a description (recommended but optional).
  6. Select public or private. You will need the repo to be public to publish a website from it, but you may choose to keep it private initially.
  7. click Create repository.

See these GitHub instructions for more details.

2. Create or associate a project dashboard to track your work. (Optional)

This step is optional; do it if you want to specify a particular dashboard to manage your issues backlog. While in your GitHub repo, click the Projects tab and either create a new project using the +New project button or associate an existing project with your repo using the Link a project button to browse the list of current projects and pick one to use.

If you don't specify a project in the next step of this process, the default will be used, #39: Misc. Alliance Tasks.

If you don't want to use a dashboard at all, relying instead on the issues list in the repo, then search the *.markdown files and the .github/**/*/yaml files for references to a "dashboard" and delete them.

If you create a new project or decide to use a different one from the default, note the dashboard number in the URL; you'll need it for the next step.

At this time, the project number N is used in the following places: 1. The projects: [The-AI-Alliance/N] entries in .github/ISSUE_TEMPLATE/*.yaml files. 1. The line in docs/contributing.markdown with See also the [project board](https://github.com/orgs/The-AI-Alliance/projects/N/).

3. Convert the placeholder variables.

Note

This step is the only one where you need to work locally on your laptop, vs. working through the GitHub UI. It won't be feasible on Windows machines. If you have any problems doing this step, ask Dean Wampler for help.

Now you have to use the git command-line tool, which is built into MacOS, to clone your repo locally and run a script that replaces placeholder variables with the values that are correct for your repo.

Open the terminal application. It will show a command prompt at your home directory, e.g., /Users/deanwampler for Dean Wampler.

Type in the following command for your repo:

git clone https://github.com/The-AI-Alliance/REPO_NAME_MACRO.git
cd REPO_NAME_MACRO

Here cd is the change directory command that changes your current working directory to be the root directory of the repo you just cloned.

Now, if you are using this repo for a website, all the website content is under the docs directory. However, the script also edits the top-level README.md, Makefile, and possibly other files.

Your new repo will have placeholder values for the project name, associated focus area, etc. We'll fix those values using the "shell" script finish-microsite.sh, which replaces the placeholder variables with appropriate strings for your project.

To see the available required and optional arguments, run this command:

./finish-microsite.sh --help

If you run the script without any arguments, it will prompt you for all the values. There are a lot of them, but only the first few values require your input; default values are shown for all the others, which are usually sufficient:

./finish-microsite.sh

You can also specify the required arguments directly, which is faster if you know what to use. Currently, there is only one required argument, the human-readable title for the website. For example, for a repo named ai-for-evil-project, the required command would be the following:

./finish-microsite.sh --microsite-title "AI for Evil Project"

Note

The title has to be in quotes if it has nested white space.

Additionally, the following information is important:

Note

  1. The script will try to use zsh. If you don't have zsh, but you have bash version 5 or later, then use bash ./finish-microsite.sh ... to run the script.
  2. To see the current list of required and optional arguments, run the script with the --help flag.
  3. By default, the website will be published from the main branch. If you prefer to use a different branch, we have used latest as a convention for many of the microsites. In this case, add the flag --use-latest. If you prefer to use a different branch name BRANCH, use --publish-branch BRANCH.
  4. The script replaces the content of README.md with the content form README-template.md (modified with variables replaced), and removes README-template.md from the repo.

Warning

After the script makes changes, it pushes them from the local repo to the upstream repo in GitHub. If you don't want to do that, preferring to push changes upstream later, then add the option --no-push. Pushing upstream may fail depending on how your personal GitHub account is configured, etc. Talk to Dean Wampler if you have problems here.

4. Edit the website buttons.

Note

From this point forward, all the subsequent steps can be done on the GitHub UI for your repo.

There are purple "header buttons" that appear on all pages in the website. You can see examples in existing websites, e.g., OTDI. The buttons are defined as HTML anchor tags (<a href="...">...</a>) in the file docs/_includes/header_buttons_custom.html.

Note that any anchor tags with external links should include target="_blank", while internal links, like the default button link in the file for Join This Project, don't use external targets.

Edit this file to define buttons that work for you. If you don't want any buttons, delete the contents of the file, but don't delete the file.

5. Add your initial custom content for the pages in the docs directory.

There are various TODO and example "idioms" in the docs/**/*.markdown, README.md, and other files that you should replace with your real content as soon as possible, e.g.,

  1. Find and replace all occurrences of TODO with appropriate content.
  2. Rename or delete the second_page.markdown. Copy it to add more top-level pages, but change the nav_order field to control the order of the pages shown in the left-hand side navigation view.
  3. Rename or delete the nested folder and its contents, which is an example of how to create nested content.

Tip

Start with 10, 20, etc. for the nav_order of top-level pages, giving yourself room to insert new pages in between existing pages. For nested pages, e.g., under 20, use 210, 220, etc.

  1. See the nested directory content as an example of how to do nesting. Note that the metadata fields at the top also define the parent and has_children fields.
  2. Make any changes you want to make in the docs/_config.yml file. (None are mandatory.)

For more tips and guidance on development tasks, see also the links for more information in the README.md in your new repo. Add a project-specific description at the beginning of that file.

6. Add your initial custom content to the README.md in the repo.

The README.md contains useful boilerplate for contributors, but the preamble at the beginning should be customized with useful "welcome" information about the project.

7. Merge changes to the latest (or another) branch. (Optional)

By default, the website is published from the main branch, for convenience. However, if you chose to use the latest branch or another branch (see step 2. above), you'll need to merge the changes in main to that branch. We won't provide instructions here, as this is a standard developer practice. However, ask one of the developers on the team for help if needed.

8. Edit the content of AGENTS.md and SECURITY.md

AGENTS.md is a helper file for coding agents. You will need to update it periodically as your project evolves and expands

SECURITY.md defines the project security policy.

9. Edit the repo's Settings.

To publish the website and setup some other repo features, click the Settings "gear" on the upper right-hand side of the repo's top-level page.

9a. Click the checkbox labeled Require contributors to sign off on web-based commits Loading.

We require DCO ("Developer Certificate of Origin") checks for all commits. Setting this checkbox turns this on automatically for users making repo edits in the GitHub Web UI.

9b. Enable discussions.

Scroll down to Features and click Discussions to enable them. Click the Set up discussions button and edit the first discussion topic to taste, then post it.

However, if you don't want to enable discussions, then remove the URL on the docs/contributing.markdown page.

9c. Publish your website.

On the left-hand side of the Settings, click the link for Pages. Under Branch, select your publication branch, either main, latest, or a custom branch you specified above. Then select the /docs directory and finally, click Save.

Your website should be published after a few minutes to `https://the-ai-alliance.github.io/REPO_NAME_MACRO/``.

Tip

At the top of the repo page, click Actions to see the progress of building your website. This action will be executed every time you make a change to a file in your publication branch (i.e., main by default). If for some reason building the website fails, this page can provide useful debugging help.

9d. Configure Dependabot

On the left-hand side of the Settings page, click the link for Advanced Security. Enable all the alerts and security updates.

For the Dependabot version updates section, the configuration should already be correct. (It is defined in the included .github/dependabot.yml file.) However, you can click the Configure button to change it.

9e. Configure the Default Branch

If you don't want to use main as the default integration branch, go to the General panel and configure the default branch you want to use.

Warning

The website, READMEs and other documentation often refer to main as the default branch. Change those references to the new branch name.

9f. Define Branch Protection Rules

Consider defining branch protection rules under the Branches panel. See other repos, like Tapestry, for examples.

9g. Enable Security Scans

Under the Security and Quality panel, the SECURITY.md file already defines the security policy. Enable any or all of the quality and security checks shown on this panel.

10. Add your website to the Alliance GitHub organization page and the Alliance website.

Note

This step applies for code repos, not just documentation repos.

Add the website to the Alliance GitHub organization README and the Alliance GitHub Pages website.

When you are ready for broader exposure for your site, there are a few places where we have an index to all the “microsites” and some code-centric projects without microsites.

  1. First find the best place in the https://github.com/The-AI-Alliance/ (README.md direct link) or one of the other related Markdown files.
  2. Make the same change in the corresponding *.markdown page in the GitHub organization microsite: https://the-ai-alliance.github.io/ (index.markdown direct link or sibling pages.)

Note

You only need to edit the appropriate .github file (step #1), because we can automatically propagate the changes to the second file.

  1. Find the right section in the README.md or related page where your project belongs.
  2. Find the correct table row in the section where it should be inserted.
  3. Copy the two rows (<tr>...</tr>) either above or below this point and insert them.
  4. Edit all the details in the rows accordingly for your project. Note that if you didn't create a project dashboard in the previous step, you will delete that item in one of the table cells (<td>...</td>). You may decide to add or remove other links, too.

After editing the .github page, notify Dean Wampler (email, Slack), who will run a tool that will copy the changes to the https://the-ai-alliance.github.io/ site. (This process is described in the the-ai-alliance.github.io repo.)

11. Add Your Source Code

If your project will have Python source code, the Makefile includes .common.mk, which defines standard targets like unit-tests, format, lint, and type-check. All of these targets are built by the before-pr target, which we recommend you run and ask collaborators to run before submitting a PR.

These targets assume that your Python source code files will be under src and the test files are under src/tests.

Note

The built-in pytest target fails unless there are tests under src/tests. Hence, it is disabled by default in Makefile. See the target unit-tests-command defined there and the comments above it.

There is a workflow .github/workflows/ci.yml, which you will have to enable for PRs in the Rulesets / main-pr-enforcement (under project Settings > Rules > Rulesets), if and when you add source code. This CI workflow is only triggered for source-related content, i.e., Makefile, .*.mk, *.toml, and src/** files. It doesn't do anything for the microsite content under docs. It's harmless to set it up now, so you don't forget about it later.

Warning

Cloning the microsite-template repository doesn't appear to set this up automatically, even though this ruleset is configured the microsite-template repository. The easiest way to do this is to click the Protect this branch button shown in this prompt on the landing page for your new repository: Branch protection rule prompt Then fill in the form that pops up. In particular, select Require status checks to pass, then click Add checks, type in ci, and select it.

The workflow assumes your integration branch is main (edit as required) and it runs the task make before-pr on PRs to that branch.

Tip

  1. Try make before-pr. It should print a lot of "stuff", but not do anything when you first create this repository. It should also not fail!
  2. For other examples of how the make process is used see the Tapestry and the ai-application-testing projects.
  3. Edit CODEOWNERS to designate owners responsible for different sections of the repository.
  4. Update AGENTS.md to add any useful information for coding agents to understand about the code structure, purpose, etc.

12. Delete the files README-instructions.md, finish-microsite.sh, and any of the LICENSES/LICENSE.* files that don't apply to your project.

The first two files,README-instructions.md (this file!) and finish-microsite.sh, are no longer needed, so you can remove them from your repo. Select each one in the GitHub UI and click the ... menu on the upper right-hand side, then select Delete file.

Similarly, you may not need all three LICENSE.* files:

  • LICENSES/LICENSE.Apache-2.0: Recommended for code.
  • LICENSES/LICENSE.CC-BY-4.0: Recommended for documentation.
  • LICENSES/LICENSE.CDLA-2.0: Recommended for datasets.

13. Final Steps

If you are using a separate publication branch, e.g., latest, don't forget to merge all changes from main to the publication branch and push both branches upstream, e.g., git push --all (when using the CLI in a terminal).

You should now have a published website and you should know how to edit the content.

Need Help?

Reach out to Dean Wampler (email, Slack) or Joe Olson (email, Slack) if you need help.