flow. ci 를 사용 하여 프로젝트 문 서 를 빠르게 발표 합 니 다.

소프트웨어 연구 개발 의 협력 과정 에서 문 서 는 없어 서 는 안 될 부분 으로 문서, 인터페이스 문서, 사용 문서 등 이 필요 하 다.문 서 를 쓰기 시 작 했 을 때 먼저 두 가지 문제 가 발생 합 니 다.

팀 원 간 에 어떻게 협력 합 니까?

문 서 는 OK 후에 어떻게 나 눠 주 고 어디로 보 러 갑 니까?어떻게 업데이트 합 니까?

이 르 면 워드 + ppt 로 문 서 를 만 들 고 공유 서버 (ftp, 삼바) 에 올 리 는 방식 으로 문서 잠 금 과 덮어 쓰 는 문제 가 있 을 수 있 습 니 다. 몇 명의 작은 팀 은 괜 찮 습 니 다. 업데이트 할 때 "문 서 를 업데이트 하 겠 습 니 다. 여러분 은 어떤 파일 을 차지 하지 마 세 요 (windows 로 문 서 를 공유 하 는 동 화 를 사용 하 는 것 이 익숙 할 것 입 니 다)" 라 고 소 리 쳤 습 니 다.업 데 이 트 를 마치 고 다시 한 번 소 리 를 질 러 야 한다.그 밖 에 워드 파일 형식 (워드 파일 은 압축 패키지 로 많은 xml 과 다른 파일 로 구성 되 어 있 습 니 다) 이 너무 복잡 하기 때문에 git 나 svn 을 통 해 버 전 통 제 를 하 더 라 도 충돌 이 발생 하면 육안 통합 과 충돌 을 해결 하기 어렵 습 니 다.
그렇다면 상술 한 문 제 를 어떻게 해결 할 것 인가?이 글 은 gitbook + flow. ci 로 문서 의 발표, 통합 과 배 치 를 진행 하여 필요 한 학생 들 에 게 참고 하 기 를 바 랍 니 다.
문서 협업 & 버 전 관리 방법 (git + markdown)
개발 팀 은 git 나 svn 을 협력 과 버 전 관리 도구 로 사용 하 는 것 은 이미 성숙 한 방안 입 니 다. 물론 문서 에 도 사용 할 수 있 습 니 다. 다만 워드 문서 자체 가 버 전 관리 에 적합 하지 않 습 니 다. markdown 은 경량급 의 태그 언어 로 학습 이 간단 하고 손 이 쉽 습 니 다 (구체 문법 참고 http://wowubuntu.com/markdown/. git 와 결합 하면 완벽 한 문서 버 전 통 제 를 할 수 있 습 니 다.
문서 발표 방법 (gitbook + nginx)
가장 좋 은 방법 은 문 서 를 웹 사이트 로 발표 하 는 것 이다. 이렇게 하면 어떠한 도 구 를 설치 하지 않 아 도 문 서 를 볼 수 있 고 업데이트 할 때 사 이 트 를 업데이트 하면 된다.여기 서 gitbook 으로 markdown 파일 을 사이트 로 빠르게 생 성 합 니 다.
gitbook 이 뭐 죠?홈 페이지 에 이렇게 소개 되 어 있 습 니 다.

GitBook is a modern publishing toolchain. Making both writing and collaboration easy.

쉽게 말 하면 markdown 문 서 를 html, pdf, epub 등 다양한 형식 으로 바 꾸 는 것 이다. 많은 오픈 소스 소프트웨어 와 책 은 gitbook 으로 발표 된다. 예 를 들 어 Elasticsearch 권위 지침, Docker - 입문 부터 실천 등 이다.
markdown 문 서 를 정적 html 로 만들어 서버 (nginx) 에 배치 하면 브 라 우 저 를 통 해 볼 수 있 을 뿐만 아니 라 server 를 업데이트 하면 모든 사람 이 볼 수 있 는 최신 문서 입 니 다.
문 서 를 지속 적 으로 통합 & 배치 하 는 방법 (flow. ci)
CI (Continuous Integration) 는 '지속 적 통합' 이라는 뜻 으로 코드 의 지속 적 인 테스트 및 기타 코드 수정 과 의 통합 과 병합 을 말한다.
CD (Continuous Deployment) 는 '지속 적 인 배치' 라 는 뜻 으로 코드 와 패 치 의 지속 적 인 배 치 를 전체 코드 라 이브 러 리 에 말 합 니 다.
문 서 를 보면 지속 적 인 배 치 는 내용 의 지속 적 인 테스트 와 수정 이 필요 한 병합 과 배치 이다.배 치 는 발표 라 는 뜻 이다.예 를 들 어 '배치 문서' 는 출력 파일 이 웹 서버 에 복사 되 어 열람 되 는 것 을 말한다.
지속 적 인 통합, 지속 적 인 배 치 는 한두 마디 로 분명하게 말 할 수 있 는 것 이 아니 라 지속 적 인 통합, 지속 적 인 배 치 를 실현 하 는 도구 체인 도 다양 하 다. 예 를 들 어 가장 흔히 볼 수 있 는 jenkins, TravisCI 등 은 사용 하기에 너무 복잡 하 다.이 글 에서 저 는 자신의 지속 적 인 통합 서비스 인 flow. ci 를 사용 하여 문서 의 통합 과 배 치 를 진행 할 것 입 니 다. 참고 하 시기 바 랍 니 다.
git repo 저장 문서 만 들 기
우선, git repo 저장 문 서 를 만 듭 니 다. flow. ci 공식 문서 docs. flow. ci 를 예 로 들 면 git repo 는[email protected]:FIRHQ/flow.ci.git
현재 flow. ci 는 github, bitbucket, 국내의 coding 과 개인 배 치 를 지원 하 는 Gitlab 입 니 다.문서 가 위 코드 창고 에 있 는 git repo 만 있 으 면 flow. ci 를 사용 하여 통합 할 수 있 습 니 다. flow. ci 에서 프로젝트 를 만 드 는 방법 은 문 서 를 참고 할 수 있 습 니 다.
flow. ci 에 flow 만 들 기
이 어 flow. ci 에 flow 를 만 들 고 언어 템 플 릿 은 nodejs (gitbook 을 사용 하려 면 node 환경 이 필요 합 니 다) 를 사용 합 니 다.
동시에 Cache, Install, Test 등 step 를 삭제 합 니 다. 이 몇 step 는 nodejs 프로젝트 에 제공 되 는 것 입 니 다. 우 리 는 nodejs 가 실 행 될 때 환경 과 npm 도구 만 필요 합 니 다.
사용자 정의 스 크 립 트 step 추가
삭제 후 사용자 정의 스 크 립 트 step 를 추가 합 니 다. 사용자 정의 스 크 립 트 step 를 추가 하 는 방법 은 문 서 를 참고 할 수 있 습 니 다.사용자 정의 스 크 립 트 두 개 를 추가 합 니 다. 하 나 는 gitbook 을 설치 하고 하 나 는 문 서 를 컴 파일 하고 발표 하 는 데 사 용 됩 니 다.
gitbook 을 설치 한 사용자 정의 스 크 립 트 step 내용

flow_cmd "npm install gitbook-cli -g" --echo --retry --assert

이곳 의 flowcmd 는 flow. ci 가 제공 하 는 함수 입 니 다. 명령 을 실행 하 는 데 실패 하면 다시 시도 합 니 다.
정적 파일 생 성 & 배치 사용자 정의 스 크 립 트 step 내용

if [ "$FLOW_GIT_BRANCH" == "gitbook" ]; then #     gitbook  
  source get_commits_from_last.sh
  bash -x ./deploy.sh 
fi;

$FLOW_GIT_BRANCH 는 환경 변수 로 현재 git 분기

를 저장 합 니 다.

get_commits_from_last.sh 지난번 에 발 표 된 날짜 와 git commt id

를 가 져 옵 니 다.

deploy.sh gitbook 명령 으로 markdown 문 서 를 컴 파일 하고 첫 페이지 head 에 이번 commt id 번호 와 시간 스탬프 를 추가 하여 서버 에 발표 합 니 다. 스 크 립 트 는 마지막 으로 방 송 됩 니 다

gitbook 에서 생 성 된 정적 파일 을 scp 방식 으로 서버 에 복사 하기 때문에 서버 에 rsa key 신뢰 를 추가 해 야 합 니 다. rsa - key 는 프로젝트 설정 페이지 에서 찾 을 수 있 습 니 다. 이에 대응 하 는 user 의 ~ /. ssh / authorized 를 추가 할 수 있 습 니 다.keys 중

메 일 알림 을 추가 하 는 step, 문서 배치 성공 후 터치
Email Sender 플러그 인 은 메 일 수신 자, 메 일 테마, 메 일 내용 템 플 릿 등 세 가지 인자 가 필요 합 니 다. 다음 과 같 습 니 다.
총결산
이로써 flow. ci 를 사용 하여 문 서 를 빠르게 발표 하 는 절차 가 모두 완료 되 었 습 니 다.flow. ci 는 지속 적 으로 통합 되 고 지속 적 으로 배 치 된 도구 가 아니 라 자동화 의 시각 으로 번 거 로 운 일 을 살 펴 보고 새로운 사물 에 더 많은 시간 을 사용 하도록 도와 준다.
궁금 한 게 있 으 면 메 일 로 보 내 주세요[email protected], 당신 의 관점 을 공유:)
모든 step 에서 언급 된 스 크 립 트 를 첨부 합 니 다:

get_commits_from_last.sh

#!/usr/bin/env bash
# usage: sh get_commits_from_last.sh
#  export 2     :
#    DEPLOY_DIFF          
#    DEPLOY_LOG          

set -e

STAGE="docs"
URL="${STAGE}.flow.ci"
HTML=`eval curl -sS ${URL}` #     html

#    html         ID       
LAST_ID=`echo $HTML | awk 'match($0, /-[0-9a-f]{7}/) { print substr( $0, RSTART+1, RLENGTH-1 )}'`
LAST_TIME=`echo $HTML | awk 'match($0, /[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}/) { print substr( $0, RSTART, RLENGTH )}'`"Z"


FMT="%Y-%m-%dT%H:%M:%SZ"
currDate=`date -u +"$FMT"`

if [[ `uname` == 'Darwin' ]]; then
  ts=$(date -j -f "$FMT" "${currDate}" "+%s")
  ts2=$(date -j -f "$FMT" "${LAST_TIME}" "+%s")
else
  ts=$(date --date="${currDate}" +"%s")
  ts2=$(date --date="${LAST_TIME}" +"%s")
fi

(( diff=(ts-ts2)/60 ))

export DEPLOY_DIFF=$diff
echo "Last $1 version : $LAST_ID @ ${LAST_TIME} (${DEPLOY_DIFF} minutes ago)"
echo "-----------------------------------------"
export DEPLOY_LOG=`git log --oneline $LAST_ID..HEAD`
echo "${DEPLOY_LOG}"

deploy.sh

#!/bin/bash

set -e

# VARS
DEPLOY_TIME=`date +%Y%m%d%H%M%S`
REMOTE_DIR="/var/www/flow-doc"
RELEASE_DIR="${REMOTE_DIR}/release"
DEPLOY_DIR="${RELEASE_DIR}/${DEPLOY_TIME}"
LATEST_DIR="${REMOTE_DIR}/latest"

TARGET=prod
USER=deploy #     rsa key   
HOST="     server ip"
PORT=22 # ssh  

#   gitbook       
gitbook build docs dist

#       
FMT="%Y-%m-%dT%H:%M:%SZ"
currDate=`date -u +"$FMT"`
if [[ `uname` == 'Darwin' ]]; then
  ts=$(date -j -f "$FMT" "${currDate}" "+%s") 
else
  ts=$(date --date="${currDate}" +"%s")
fi

#       
branch=$(git rev-parse --abbrev-ref HEAD)
if [ -n "$FLOW_GIT_BRANCH" ] ; then
  branch=$FLOW_GIT_BRANCH
fi

#   commit log
commit=$(git rev-parse --short HEAD)

#          COMMIT ID      html 
sed -i '/author/a\ \' ./dist/index.html
sed -i '/author/a\ \' ./dist/index.html

sed -i "s/COMMIT-TAG/${branch}-${commit}/g" ./dist/index.html
sed -i "s/UPDATE-TIME/${currDate}/g" ./dist/index.html

#     
echo "########## Deploy to ${TARGET} ##########"
ssh ${USER}@${HOST} -p ${PORT} "mkdir -p ${DEPLOY_DIR}"
ssh ${USER}@${HOST} -p ${PORT} "rm -rfv ${LATEST_DIR}"

scp -P ${PORT}  -rv ./dist/* ${USER}@${HOST}:${DEPLOY_DIR}
ssh ${USER}@${HOST} -p ${PORT} bash -x <