해당 포스트는 Hadley Wickham이 작성한 'The tidyverse style guide' 를 번역하여 정리한 글입니다.
Lists
Intro - 0. Welcome
Analysis - 1. Files
Analysis - 2. Syntax (1)
Analysis - 2. Syntax (2)
Analysis - 3. Functions
Analysis - 4. Pipes
Analysis - 5. ggplot2
Packages - 6. Files
Packages - 7. Documentation
Packages - 8. Tests
Packages - 9. Error messages
Packages - 10. News
Packages - 11. Git/GitHub
10. 뉴스 (News)
각 사용자가 직면한 패키지 변경 사항은 NEWS.md 파일에 글머리 기호로 첨부되어야 합니다. 문서에 대한 사소한 변경 사항은 문서화할 필요는 없지만 전면적인 변경사항과 새로운 변경사항에 주의를 기울이는 것이 좋습니다.
10.1 글머리 기호(Bullets)
글머리 기호(bullets)의 목표는 변경 사항을 간략하게 설명하여 패키지 사용자가 변경된 내용을 이해할 수 있도록 하는 것입니다. 이것은 커밋 메시지(commit message)와 유사할 수 있지만, (개발자가 아닌) 사용자를 염두에 두고 작성됩니다.
새로운 글머리 기호는 파일의 맨 위에 추가해야 합니다(첫 번째 제목 아래). 글머리 기호의 구성은 나중에 릴리스(release) 과정에서 발생합니다(Section 10.2.2).
10.1.1 일반 스타일(General style)
가능한 글머리 기호의 시작 부분에 함수 이름을 배치하는 것이 좋습니다. 일관된 위치는 글머리 기호를 스캔하기 쉽고 릴리스(release) 전에 구성하기 쉽게 만들어 줍니다.
# Good
* `ggsave()` now uses full argument names to avoid partial match warning (#2355).
# Bad
* Fixed partial argument matches in `ggsave()` (#2355).줄(Lines)은 80자를 기준으로 줄 바꿈해야하며 각 글머리 기호는 완성형으로 끝나야 합니다.
글머리 기호는 틀(frame)을 분명히 해야하며(즉, 과거에 있었던 일이 아닌 지금 일어나는 일), 현재 시제를 사용해야 합니다.
# Good
* `ggsave()` now uses full argument names to avoid partial match warnings (#2355).
# Bad
* `ggsave()` no longer partially matches argument names (#2355).많은 뉴스(news) 글머리 기호는 한 문장이 될 것입니다. 이는 일반적으로 버그 수정(bug fix) 또는 사소한 개선(minor improvement)을 설명할 때 적절하지만, 새로운 기능을 설명할 때에는 더 자세한 정보가 필요할 수 있습니다. 보다 복잡한 기능을 사용하려면 펜싱된 코드 블록(fenced code blocks, ```)에 더 긴 예제를 포함하시는게 좋습니다. 이것들은 나중에 블로그 게시물을 작성할 때 유용한 영감을 줄 것 입니다.
# Good
* In `stat_bin()`, `binwidth` now also takes functions.
# Better
* In `stat_bin()`, `binwidth` now also takes functions. The function is
called with the scaled `x` values, and should return a single number.
This makes it possible to use classical binwidth computations with ggplot2.
# Best
* In `stat_bin()`, `binwidth` now also takes functions. The function is
called with the scaled `x` values, and should return a single number.
With a little work, this makes it possible to use classical bin size
computations with ggplot2.
```R
sturges <- function(x) {
rng <- range(x)
bins <- nclass.Sturges(x)
(rng[2] - rng[1]) / bins
}
ggplot(diamonds, aes(price)) +
geom_histogram(binwidth = sturges) +
facet_wrap(~cut)
`` ` 10.1.2 답신(Acknowledgement)
글머리 기호가 이슈(issue)와 관련된 경우 이슈 번호(issue number)를 포함하는 것이 좋습니다. 기여도(contribution)가 PR이고 작성자가 패키지 작성자가 아닌 경우 GitHub 사용자 이름을 포함하십시오. 두 항목 모두 괄호로 묶여야하며 일반적으로 최종 기간 전에 나오게 됩니다.
# Good
* `ggsave()` now uses full argument names to avoid partial match warnings
(@wch, #2355).
# Bad
* `ggsave()` now uses full argument names to avoid partial match warnings.
* `ggsave()` now uses full argument names to avoid partial match warnings.
(@wch, #2355)10.1.3 코드 스타일(Code style)
함수, 인수 및 파일 이름은 백틱(backticks, )으로 묶어야 합니다. 함수 이름은 괄호를 포함해야 하며, "인수(the argument)" 또는 "함수(the function)"를 생략하시는 것이 좋습니다.
# Good
* In `stat_bin()`, `binwidth` now also takes functions.
# Bad
* In the stat_bin function, "binwidth" now also takes functions.10.1.4 공통 패턴(Common patterns)
tidyverse 뉴스 항목에서 발췌한 다음 내용은 유용한 템플릿을 제공합니다.
- 새로운 기능군(New family of functions):
* Support for ordered factors is improved. Ordered factors throw a warning
when mapped to shape (unordered factors do not), and do not throw warnings
when mapped to size or alpha (unordered factors do). Viridis is used as
default colour and fill scale for ordered factors (@karawoo, #1526).
* `possibly()`, `safely()` and friends no longer capture interrupts: this
means that you can now terminate a mapper using one of these with
Escape or Ctrl + C (#314).- 새로운 기능(New function):
* New `position_dodge2()` provides enhanced dogding for boxplots...
* New `stat_qq_line()` makes it easy to add a simple line to a Q-Q plot.
This line makes it easier to judge the fit of the theoretical distribution
(@nicksolomon).- 기존 기능에 대한 새로운 주장(New argument to existing function):
* `geom_segment()` gains a `linejoin` parameter.- 함수 인수의 행동 변경(Function argument changes behaviour):
* In `separate()`, `col = -1` now refers to the far right position.
Previously, and incorrectly, `col = -2` referred to the far-right
position.- 함수 변경 동작(Function changes behaviour):
* `map()` and `modify()` now work with calls and pairlists (#412).
* `flatten_dfr()` and `flatten_dfc()` now aborts with informative
message if dplyr is not installed (#454).
* `reduce()` now throws an error if `.x` is empty and `.init` is not
supplied.10.2 조직(Organisation)
10.2.1 개발(Development)
개발(development) 중 새로운 글머리 기호를 추가하는 경우, 파일 상단의 "개발(development)" 제목 바로 아래에 추가해야 합니다.
# haven (development version)
* Second update.
* First update.10.2.2 릴리스(Release)
릴리스(release)하기 전에 NEWS 파일을 철저히 교정하고 정리해야 합니다.
각 릴리스(release)에는 패키지 이름과 버전 번호를 포함하는 레벨1(level1) 머리글(#)이 있어야 합니다. 소규모 패키지(smaller packages) 또는 패치 릴리스(patch releases)의 경우 이 정도 조직이면 충분할 수 있습니다. 아래는 "modelr 0.1.2" 에 대한 NEWS 예시 입니다.
# modelr 0.1.2
* `data_grid()` no longer fails with modern tidyr (#58).
* New `mape()` and `rsae()` model quality statistics (@paulponcet, #33).
* `rsquare()` use more robust calculation 1 - SS_res / SS_tot rather
than SS_reg / SS_tot (#37).
* `typical()` gains `ordered` and `integer` methods (@jrnold, #44),
and `...` argument (@jrnold, #42).글머리 기호가 많은 경우, 버전 머리글 뒤에 레벨2(level2) 머리글(##)을 이용하여 관련 영역으로 그룹화된 문제가 따라와야 합니다. 일반적으로 사용되는 3가지 섹션은 다음과 같습니다.
# package 1.1.0
## Breaking changes
## New features
## Minor improvements and fixes다른 구조가 합리적이라면 이러한 머리글을 사용하지 않아도 됩니다. 실제로, 더 큰 패키지는 종종 더 세분화된 분류를 요구할 수 있습니다. 예를 들어, "ggplot2 2.3.0"에는 다음과 같은 머릿글들이 포함되어 있습니다.
# ggplot 2.3.0
## Breaking changes
## New features
### Tidy evaluation
### sf
### Layers: geoms, stats, and position adjustments
### Scales and guides
### Margins
## Extension points
## Minor bug fixes and improvements
### Facetting
### Scales
### Layers
### Coords
### Themes
### Guides
### Other일반적으로 그룹이 어떻게 구성될지 미리 알 수 없으므로 개발중에는 글머리 기호로 머리글을 구성하는 것은 가치가 없습니다.
섹션 내에서 첫 번째 언급된 함수에 따라 글머리 기호는 알파벳순으로 정렬되어야 합니다. 함수가 언급되지 않은 경우, 글머리 기호를 섹션 맨 위에 배치하는 것이 좋습니다.
10.2.3 주요 변경 사항(Breaking changes)
revdepcheck 중에 발견된 API 주요 변경 사항이 있는 경우, 변경 사항은 맨 위에 있는 자체 섹션(own section)에도 표시되어야 합니다. 각 글머리 기호에는 변경 증상에 대한 설명과 수정에 필요한 내용이 포함되어야 합니다. 글머리 기호도 해당 섹션에서 반복해야 합니다.
## Breaking changes
* `separate()` now correctly uses -1 to refer to the far right position,
instead of -2. If you depended on this behaviour, you'll need to condition
on `packageVersion("tidyr") > "0.7.2"`.10.3 블로그 게시물(Blog post)
모든 대규모 및 소규모 릴리스에 대해, 최신 뉴스는 블로그 게시물로 전환되어야 합니다. 블로그 게시물은 주요 사용자 관련 변경 사항을 강조해야 하며 자세한 내용은 릴리스 노트를 참조하시면 됩니다. 일반적으로 새로운 기능을 보여주는 예를 포함하여 새로운 기능 및 주요 개선 사항에 초점을 맞춰야 합니다. 동기 부여된 독자가 릴리스 노트에서 찾을 수 있으므로 사소한 개선 사항과 버그 수정을 설명할 필요할 필요는 없습니다.
출처
[1] The tidyverse style guide
[2] Section 10.2.2 - Release
▲ The tidyverse style guide 원문 다운받기