README

Kokkos Documentation Workflow

- Here, we summarize the steps for setting up the kokkos-core-wiki repo, and a

branch-based workflow for updating documentation in the main Kokkos project. The kokkos-core-wiki is the canonical source of Kokkos documentation "Truth".

-	Sandia employees: Creation of wholly new pages will require Review and Approval (R&A).  Check with your Sandia team lead, if you have questions about the R&A process.

-	STEP 1) Create your own fork of the kokkos-core-wiki repo by navigating to
				`https://github.com/kokkos/kokkos-core-wiki`, and clicking "Fork" in the upper
				right of the github page.

-	STEP 2) Clone your forked repo, and add it as a remote:

					git clone [email protected]:ajpowelsnl/kokkos-core-wiki.git
					git remote add ajpowelsnl
[email protected]:ajpowelsnl/kokkos-core-wiki.git

-	STEP 3) Add the remote repo as "origin" or "upstream", according to your
	preference.  You will create pull requests against this repo:

				`git remote add origin [email protected]:kokkos/kokkos-core-wiki.git`

-	STEP 4) Check your remotes; you should see both your fork ("ajpowelsnl")
				and the main project repo ("origin"):

					[ajpowel@kokkos-dev-2 kokkos-core-wiki]$ git remote -v
					ajpowelsnl	[email protected]:ajpowelsnl/kokkos-core-wiki.git (fetch)
					ajpowelsnl	[email protected]:ajpowelsnl/kokkos-core-wiki.git (push)
					origin	https://github.com/kokkos/kokkos-core-wiki.git (fetch)
					origin	https://github.com/kokkos/kokkos-core-wiki.git (push)

-	STEP 5) Create a topic branch in your local fork of the kokkos-core-wiki:

				`git checkout -b demo/setup`

-	STEP 6) Add the Kokkos project Wiki repo from your fork as a remote (you will push changes to this repo to preview before creating a pull request on `origin [email protected]:kokkos/kokkos-core-wiki.git`): 

				`git remote add my_wiki [email protected]:ajpowelsnl/kokkos.wiki.git`

-	STEP 7) Verify your remotes (you should now have three different repos: 
				your local, forked kokkos-core-wiki (`ajpowelsnl`), the remote kokkos-core-wiki (`origin`),
				and the Wiki associated with your forked Kokkos project (`my_wiki` below)):

			```
				[ajpowel@kokkos-dev-2 kokkos-core-wiki]$ git remote -v
				ajpowelsnl	[email protected]:ajpowelsnl/kokkos-core-wiki.git (fetch)
				ajpowelsnl	[email protected]:ajpowelsnl/kokkos-core-wiki.git (push)
				my_wiki	[email protected]:ajpowelsnl/kokkos.wiki.git (fetch)
				my_wiki	[email protected]:ajpowelsnl/kokkos.wiki.git (push)
				origin	https://github.com/kokkos/kokkos-core-wiki.git (fetch)
				origin	https://github.com/kokkos/kokkos-core-wiki.git (push)

	-	STEP 8) Set up your local topic branch track origin/main:

				git checkout main
				git branch --set-upstream-to=origin/main 
				git pull origin/main
				git show
				commit f0e10f59f50f23930a2f4eedfce3eed869344277 (HEAD -> main, origin/main)
				Merge: 7b5063e ec9f444
				Author: Damien L-G <[email protected]>
				Date:   Mon Feb 28 21:09:11 2022 -0500

				Merge pull request #3 from dalg24/fixup_gh_actions

				Fixup path gh workflow

	-	STEP 9) Update your topic branch, rebasing on origin/main:

				git checkout demo/setup
				git rebase main

	-	STEP 10) Make the desired changes (on your local topic branch), and push
					to the main project Wiki (of your fork).  Nota bene: you
					will need to use the `-f` option for the **FIRST** push; this option will overwrite existing files.  

					`git push -f my_wiki demo/setup:master`

	-	STEP 11) Preview your changes by navigating to the main project Wiki of your
					fork:

					`https://github.com/ajpowelsnl/kokkos/wiki`

	-	STEP 12) If your previewed changes are good, push your local topic branch to
					your fork of the kokkos-core-wiki to create a pull request.  Please
					note that pushes to your branch will be automatically, immediately
					deployed to your *fork* of the Kokkos project Wiki, but not to the
					main projec Wiki.  You cannot push directly to the `main` branch of the remote repo:

				git push ajpowelsnl demo/setup 
				Enumerating objects: 5, done.
				Counting objects: 100% (5/5), done.
				Delta compression using up to 40 threads
				Compressing objects: 100% (3/3), done.
				Writing objects: 100% (3/3), 305 bytes | 305.00 KiB/s, done.
				Total 3 (delta 2), reused 0 (delta 0), pack-reused 0
				remote: Resolving deltas: 100% (2/2), completed with 2 local objects.
				remote: 
				remote: Create a pull request for 'demo/setup' on GitHub by visiting:
				remote:      https://github.com/ajpowelsnl/kokkos-core-wiki/pull/new/demo/setup
				remote: 
				To github.com:ajpowelsnl/kokkos-core-wiki.git
					* [new branch]      demo/setup -> demo/setup