You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 21 Current »

Proposers

Approvers

Status

Current state:  IN PROGRESS

Discussion thread: here

JIRA:  Unable to render Jira issues macro, execution error.

Released: <Hudi Version>

Abstract

This RFC aims at improving the Hudi web documentation for users and the process of updating docs for developers.

Background

There are a few gaps we observed regarding the docs:

  • We only have one version of docs kept at the asf-site branch for the latest release.  Given that each version has new features and improvements, some involving configuration and parameter changes compared to to previous versions, the single version of docs can create confusion for users using a previous release of Hudi.
  • There's no API docs generated from the code.
  • Current process of building, testing, and deploying docs (i.e the content powering hudi.apache.org) is mostly manual.

Implementation

To address these gaps, restructuring of the docs is needed to make the process easier. Migration with Travis-ci, it can build the asf-site branch and execute callback scripts.

The diagram below shows the workflow.

Key Points

There are several key points need to consider:

  • How to migration with travis-ci
  • How to use git command safely in travis-ci (important)

To use git command safely, hidden the password, we need use bellow form.

git clone https://${GIT_TOKEN}@github.com/${GIT_REPO}/${GIT_PROJECT}.git

Steps to get the {GIT_TOKEN}

Steps - 01 : Enable two-factor authentication

https://help.github.com/en/github/authenticating-to-github/about-two-factor-authentication


Steps - 02 : Generate personal access tokens

https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line

Steps to migration with travis-ci

Steps - 01 : Active repository

Steps - 02 : Add {GIT_TOKEN} to environment variables

Steps - 03 : Add .travis.yml file to asf-site branch

language: ruby
rvm:
  - 2.6.3

git:
  clone: false

env:
  global:
    - GIT_USER="CI BOT"
    - GIT_EMAIL="cibot@test.com"
    - GIT_REPO="apache"
    - GIT_PROJECT="incubator-hudi"
    - GIT_BRANCH="asf-site"
    - DOCS_ROOT="`pwd`/${GIT_PROJECT}/docs"

before_install:
  - git config --global user.name ${GIT_USER}
  - git config --global user.email ${GIT_EMAIL}
  - git clone https://${GIT_TOKEN}@github.com/${GIT_REPO}/${GIT_PROJECT}.git
  - cd ${GIT_PROJECT} && git checkout ${GIT_BRANCH}
  - gem install bundler:2.0.2

script:
  - pushd ${DOCS_ROOT}
  - bundle install
  - bundle update --bundler
  - bundle exec jekyll build _config.yml --source . --destination _site
  - popd

after_success:
  - \cp -rf ${DOCS_ROOT}/_site/* test-content
  - git add -A
  - git commit -am "Travis CI build asf-site"
  - git push origin asf-site --force

branches:
  only:
    - asf-site


Steps - 04 : Check whether ci works well or not

End

Hope, this will works well

Test

had test https://github.com/lamber-ken/lamber-ken.github.io, when commits, it will generate docs and push the content to asf-site branch.



  • No labels