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 to 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.  You cannot push directly to the `main` branch of the remote repo:

				git push -f 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