NEWS.MD

R package의 NEWS 파일 작성

Why and how maintain a NEWS file for your R Package?

사실 처음부터 완벽한 Package는 없다.

새로운 기능을 추가 해야할 때도 있고, deprecated function을 제거 해야 한다던지, 아무튼 Archived 되지 않는 이상, package는 계속 변화 할 수 밖에 없다.

---

changelog 를 작성하는 이유

4가지 중에 요약하면 2가지 이다.

• developer 본인을 포함한 여러 user에게, 변화의 내용을 알리기 위해서
• contributor를 표기 하기 위해 (acknowledgment)

---

그러면 왜 NEWS.md 방식으로 작성을 하는가

changelog 작성에는 NEWS.Rd, NEWS.md, NEWS, inst/NEWS 등 여러 방식이 있다.

CRAN 패키지 기준으로, changelog 형태는

• inst/NEWS.Rd : 134개
• inst/NEWS : 413개
• NEWS : 1055개
• NEWS.md : 1174개

NEWS.md가 제일 많은데 NEWS.md가 추천 되는 이유는 아래와 같다.

• md는 Rmarkdown을 썼으면 쉽게 쓸 수 있음.
• pkgdown을 썼으면 NEWS.md가 자동적으로 changelog page를 생성함
• usethis는 news.md를 자동적으로 생성해줌 (usethis::use_news_md()

그리고 단점은

• utils::news()에서 commonmark랑 xml2가 없으면 에러 난다.
• github 기준으로, NEWS.md는 자동적으로 렌더링 되지 않는다고 함
• 때문에, RMarkdown 킹 Yihui Xie가 inst/NEWS.Rd를 쓰는것으로 유명 issue

솔직히 단점은 무슨 말인지 잘 와닿지가 않는다, 내가 news.md를 안써봐서 그런가…

---

NEWS.md의 내용은 어떤 식으로 작성 하는가

자세한 내용은 tidyverse style guide 참조

tidyverse sytle guide에서는 다음과 같이 작성하길 권장한다.

• Bullets을 사용하는 경우 (*)
  1. Bullets이후엔 함수의 이름을 기록할 것
  2. 한 줄의 내용은 80자 이하로 작성할 것
  3. 짧은 내용이 아닌, 긴 내용은 여러 줄로 나눠써 쓰기 보다는, code blocks ( `` `)를 사용
  4. 참조 issue 나 PR을 () 로 감싸서 후반 부에 작성
  5. function의 표기는 ()까지 포함, parameter는 생략
• util::news() 는 R 자체의 changelog이므로, 이걸 참조하기에 좋음.

---

NEWS의 한계점

사람들이 안 읽는다. 이를 위해서는 아래의 방법들이 권장됨

• 블로그에 post를 작성. 이후 R Weekly Repo에 PR을 올리거나, Post를 제출
• Mailing list나 Tweak를 작성.
• Package manual / Vignette에 변화 내용 작성

---

결론

쓰고 보니 별 내용이 없는 것 같다.

package 개발 할때는 usethis써라 세번써라