Name: slamdata-docs
Owner: SlamData, Inc.
Description: Documentation for SlamData, SlamData Advanced, and Quasar Advanced.
Created: 2016-03-29 18:50:00.0
Updated: 2018-03-28 09:47:19.0
Pushed: 2017-12-07 17:07:07.0
Size: 15270
Language: Python
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
SlamData documentation is a public repository on github at https://github.com/slamdata/slamdata-docs This document does not yet cover how to create a new branch.
This document assumes:
First we?ll need to clone the documentation repository so we can make changes.
ers/damon]$ mkdir git
ers/damon]$ cd git
ers/damon/git]$ git clone https://github.com/slamdata/slamdata-docs.git
ing into 'slamdata-docs'...
te: Counting objects: 1165, done.
te: Compressing objects: 100% (88/88), done.
te: Total 1165 (delta 39), reused 77 (delta 17), pack-reused 1060
iving objects: 100% (1165/1165), 12.71 MiB | 2.71 MiB/s, done.
lving deltas: 100% (594/594), done.
ers/damon/git]$ cd slamdata-docs
Whenever a specific change is needed we should create a branch to hold this change. Doing this allows us to keep focused on a single area of the documentation that needs changing. It also makes for easier review and merging later when we only have to review one section and it doesn?t compete with changes from others.
Let?s say we want to make a change Section 3 in the Administrator?s Guide. To prep for that, we could use the following commands:
damon/git/slamdata-docs]$ git checkout -b damon-admin-section3
ched to branch 'damon-admin-section3'
Now any changes we make will be limited to the damon-admin-section3 branch and will not affect either our local master copy or the remote repository.
Once the necessary changes have been made to the administrators guide, we need to make sure it looks good before committing our changes.
We currently use ReadTheDocs.org to host our documentation. It is a free service and has integration with GitHub?s branch management. This also means when you build the local docs it should look almost identical to how it looks live on the doc web site. After the prerequisites have been installed (not covered here, yet) you can make changes to the docs, build them, then test them. See the example below and know that you may see some warnings but these are typically benign.
damon/git/slamdata-docs]$ make html
nx-build -b html -d build/doctrees source build/html
ng output directory...
ing Sphinx v1.2.3
ing pickled environment... not yet created
ding [html]: targets for 12 source files that are out of date
ting environment: 12 added, 0 changed, 0 removed
ing sources... [100%] users-guide
ing for now-outdated files... none found
ling environment... done
aring documents... done
ing output... [100%] users-guide
ing additional files... genindex search
ing images... [100%] images/SD4/screenshots/date-only.png
ing static files... WARNING: html_static_path entry u'/Users/damon/git/slamdata-docs/source/_static' does not exist
ing extra files... done
ing search index... done
ing object inventory... done
d succeeded, 9 warnings.
d finished. The HTML pages are in build/html.
The process above has now created a new directory called build under the current directory. You can open the build/html/index.html file to see your local documentation now. On macOS you can simply type the following command rather than opening a browser and pointing it to the file:
damon/git/slamdata-docs]$ open build/html/index.html
Once you have made your changes and are satisfied with how they look in your locally built environment, it?s time to push them back up to github. This will push the changes to github into our damon-admin-section3 branch, but not to master yet.
It may help to first see what changes have been made:
damon/git/slamdata-docs]$ git status
ranch damon-admin-section3
ges not staged for commit:
se "git add <file>..." to update what will be committed)
se "git checkout -- <file>..." to discard changes in working directory)
modified: source/administration-guide.rst
hanges added to commit (use "git add" and/or "git commit -a")
This output is telling us that we are working with the damon-admin-section3 branch and the administration-guide.rst file has been changed but has not been staged for a commit. Files must be staged before committed. Now we can stage the file:
git/slamdata-docs/source]$ git commit -a
You?ll then be prompted (typically with your command line text editor like vi) to insert a brief description of your changes, with several lines of template information below it. The first line in the following example is what I typed, then I saved it (via :wq in vi)
ged a few lines here and there.
ease enter the commit message for your changes. Lines starting
th '#' will be ignored, and an empty message aborts the commit.
branch damon-admin-section3
anges to be committed:
modified: source/administration-guide.rst
You should see output on the command line similar to this after you save:
on-admin-section3 8a9ac39] Changed a few lines here and there.
ile changed, 1 insertion(+), 1 deletion(-)
Finally, push your local committed changes up to the working branch in GitHub:
damon/git/slamdata-docs]$ git push -u origin damon-admin-section3
ting objects: 4, done.
a compression using up to 8 threads.
ressing objects: 100% (4/4), done.
ing objects: 100% (4/4), 369 bytes | 0 bytes/s, done.
l 4 (delta 3), reused 0 (delta 0)
te: Resolving deltas: 100% (3/3), completed with 3 local objects.
ttps://github.com/slamdata/slamdata-docs.git
new branch] damon-admin-section3 -> damon-admin-section3
ch damon-admin-section3 set up to track remote branch damon-admin-section3 from origin.
Now that the remote tracking branch is setup (the -u feature) we can simply call git push without any parameters to push the changes.
You may continue to make changes using the steps from above:
status
commit -a
push
Changes have been committed. Now the changes must be approved by a team member. Go to the repository URL again https://github.com/slamdata/slamdata-docs
Update the title of the pull request if necessary and any comments in the body section and click Create pull request again:
This starts the approval workflow. Someone from the team must now go in and approve the changes before they are merged with master.
After the Pull Request has been approved and the changes have been merged into the master branch, we can push those changes to our documentation website.
The doc website has a versioning system that allows users to select which version of the documentation is displayed. The default version is latest which corresponds to the GitHub master branch. The steps below explain pushing out the latest changes to the doc web site.
Go to https://readthedocs.org/
Login
Click ?SlamData Documentation? in the list of Projects:
The build process will begin. You can click on the top most entry in the table that says Triggered if you?d like to watch the build progress. Once complete, you can visit the doc site at http://docs.slamdata.com to verify the latest branch has been updated.
Newer versions of documentation (such as v4.3, etc) will be documented in the near future. For now, this is a placeholder. A great resource is this link https://www.atlassian.com/git/tutorials/comparing-workflows which explains how we?re using the Feature Branch Workflow approach. This will require periodic refreshing of the latest branch (i.e. v4.2, or whatever is latest) from master.