Publishing the documentation

To update the Codewind website, push the content to the repo where Eclipse hosts the website.

Obtaining credentials

1. Be an Eclipse project committer.
2. Add the ssh-rsa key so that you won't be blocked from pushing the site to make it live:
   • A. Log in to https://git.eclipse.org/r/#/q/status:open.
   • B. Click your user icon and click Settings.
   • C. In Settings, click SSH Public Keys.
   • D. Now, navigate to the Terminal on your computer. Enter ~/.ssh.
   • E. Enter ls to view the contents of the file. You should see id_rsa.pub.
   • F. Enter cat id_rsa.pub to display the ssh-rsa key.
   • G. Copy the key, starting from ssh-rsa at the beginning all the way to your email address at the end.
   • H. Back on the https://git.eclipse.org/r/#/q/status:open website, return to the SSH Public Keys section of "Settings." Paste the ssh-rsa key into the key box. Add the key.

Preparing for a release

Note: To preview the release branch, follow only steps 1 through 6. If you anticipate more changes to the release branch before the release, you should be able to delete the branch you created for your preview and then create a new branch after all changes for the release are merged.

1. Open an issue for release preparation of the docs.
2. In your Terminal, go to the codewind-docs master branch. Run git fetch upstream. This command pulls in everything from your remote repository to your local repositories.
3. Then, run git log and make sure that you see your latest changes.
   • To exit out of git log, enter ^q.
4. Create a branch for the release, such as 0.4.0.
   • It's best to create a branch shortly before you are ready to publish.
   • To create a new branch with the GitHub web UI, from the Branch combo box, start from master, and then type in a new branch name.
   • Alternatively, from the command line, complete the following steps:
     • Go to your codewind-docs master branch and enter git fetch and then git pull to make sure you're up to date.
     • Enter git checkout -b <release>. (Example: git checkout -b 0.4.0)
     • Then, enter git push upstream <release>. (Example: git push upstream 0.4.0)
5. Build the codewind-docs repo for local testing.
   • A. To ensure that you have the latest content from the master branch, don't clone your fork. Instead, enter git fetch upstream. Then, create a new branch based on master with git checkout -b <branchname> upstream/<release branch>.
     • Example: git checkout -b publish040 upstream/0.4.0
   • B. Enter ./build.sh in the codewind-docs repo. It checks for internal broken links and displays an error if any exist.
     • If you find broken links, create a new PR to fix them. Merge the PR, and then try to run the ./build.sh command again.
     • For more information about fixing broken links, see Checking for broken links.
6. Test.
   • A. Run ./serve.sh. A URL, such as http://localhost:4321/codewind/, is displayed under Server address:.
   • B. Copy and paste the server address into your web browser. Look at the docs pages, and see if you can find problems like broken images.
   • C. When you are done looking at the site, press ctrl-c to stop the server. You need to stop it to restart it again.
     • In case the port is still in use, and you can't access the server, restart your computer.
     • If you restart your computer and still cannot access the server, you can edit the serve.sh file and change all 3 port numbers to any free port, such as 4322.
   • Note: If you run the ./serve.sh command and receive ERROR /favicon.ico' not found., disregard this error. It is a false positive and discussed in issue (2301)[https://github.com/eclipse/codewind/issues/2301#issuecomment-591004464]. As is, for the redirect to work on the published site, the publish will be required to be made with build.sh over serve.sh.
7. Build the files that are ready for publishing.
   • A. Run ./prepareForPublish.sh to build the files into the codewind-docs/docs/_site directory.
     • ./serve.sh is meant for local development and hard codes the host name and port number to deploy to.
     • ./serve.sh, therefore, builds the HTML redirects to point to local and not relative links.
     • Either ./build.sh or prepareForPublish.sh builds the redirects correctly, but ./prepareForPublish isolates the stage within build.sh to create the site HTML so that the link checker is not run again.
   • B. Confirm that redirects were created correctly by going to codewind-docs/docs/_site/gettingstarted.html. View the file in an editor, and check the created redirect links.
     • Correct redirect example: <a href="/codewind/learn.html">Click here if you are not redirected.</a>.
     • Incorrect redirect example: <a href="http://0.0.0.0:4321/codewind/learn.html">Click here if you are not redirected.</a>.

Pushing to the live site

1. Use cd ../ to get out of the Codewind-docs directory.
2. If you have not already done so, create a folder called codewindweb in the GitHub parent folder on your computer. If you already have a codewindweb folder, skip to step 3.
   • Note: To prevent confusion with the GitHub codewind repo (https://github.com/eclipse/codewind) folder on your computer and the website codewind repo (git://git.eclipse.org/gitroot/www.eclipse.org/codewind.git), create this new folder called codewindweb in a folder other than the one in which the GitHub codewind repo  (https://github.com/eclipse/codewind) is located.
   • A. Use cd codewindweb to go into the codewindweb folder.
   • B. To ensure that you have the latest content from the master branch, don't clone your fork. Instead, enter git clone ssh://<your_username>@git.eclipse.org:29418/www.eclipse.org/codewind.
   • C. After cloning the live website repo, you are still in the codewindweb folder. Move into the codewindweb/codewind folder before running more Git commands.
3. If you already have a codewindweb folder, enter cd codewindweb/codewind and git pull to update with the latest files.
4. Use the open . command to open Finder.
5. Enter command + a to highlight all files in codewindweb/codewind and remove them. Delete all the files except for the hidden folders since those contain git config.
6. Replace the contents of the cloned codewind folder with the files from the codewind-docs/docs/_site directory.
   • A. Go to codewind-docs/docs/_site and enter command + a and command + c to highlight all files and copy them.
   • B. Paste all copied items into the codewindweb/codewind cloned folder.
7. Commit and push in.
   • A. To view the files that you edited locally, enter git status.
     • You might see fewer files than the total amount that the team edited over the course of the release. This is normal. Files that are new or have had their names changed appear as "Untracked files," but other files don't appear under this section.
   • B. To add the file(s) to be committed, enter git add -A from the codewindweb/codewind folder.
     • Now if you enter git status, you should see the total list of all files edited over the course of the release.
   • C. To commit the files, enter git commit -s -m "<information about changes>".
   • D. To push, enter git push.

Verify your update on the Codewind.dev website.

1. Wait up to 30 minutes for the changes to go live.
   • Note: There might be multiple servers that are distributed and not all updated at once, so you might not see the updated change even if others can, or you might see the updated page on your phone but not on your laptop. In this case, just keep waiting until the updates appear.
2. Go to the website and check to make sure that the doc changes are present, that images aren't broken, and that the layout looks good, etc.
3. Check that your commit is listed on this page: https://git.eclipse.org/c/www.eclipse.org/codewind.git/

Optional steps

Adding changes into a release branch that was created too early

Release branches are protected and cannot be deleted. Ideally, we should create a release branch only after all changes for the release are merged to the master branch. However, even if changes go into master after the creation of the release branch, we can still keep the release branch and the master branch in sync:

1. From your command line, create a new branch based on the release branch with the git checkout -b <name of branch> upstream/<release_branch> command.
2. From this new branch, enter open . and delete all of the docs directory content.
3. Now, create a temporary directory in a new location. The location should be at the same level or higher than the codewind-docs directory. Create the directory with the mkdir <name of directory> command.
4. Use the cd <name of directory> command to enter the temporary directory.
5. From the temporary directory, enter git clone [email protected]:eclipse/codewind-docs.git to get the master content.
6. Copy the master content files over to the empty directory, the one that you created in step 1 with the git checkout command.
7. Enter git status. All of the changes made to master since the release branch was created appear in red.
8. Enter git add -A to prepare to pull in all of the changes. When you run git status now, the previously red files are all green. You should have no red files.
9. Create a pull request. In the GitHub web UI, make sure that the following values are set:
   • base repository: eclipse/codewind-docs
   • base: release branch
   • head repository: <your_fork_name>/codewind-docs
   • compare: <branch_where_your_changes_reside>

• Note: You cannot download the compressed file of the master branch content and then copy and paste it into the empty directory. If you try to copy and paste, GitHub counts all the pasted files as part of the change even though some have no change between the release branch and master.