You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# Package evolution - changing stuff in your package {#evolution}
5
+
# Evolução do pacote - alteração de itens em seu pacote {#evolution}
7
6
8
7
```{block, type="summaryblock"}
9
-
This chapter presents our guidance for changing stuff in your package: changing parameter names, changing function names, deprecating functions, and even retiring and archiving packages.
8
+
Este capítulo apresenta nossa orientação para alterar coisas em seu pacote: alterar nomes de parâmetros, alterar nomes de funções, depreciar funções e até mesmo retirar e arquivar pacotes.
10
9
11
-
_This chapter was initially contributed as a tech note on rOpenSci website by [Scott Chamberlain](https://github.com/sckott); you can read the original version [here](https://ropensci.org/technotes/2017/01/05/package-evolution/)._
10
+
_Este capítulo foi inicialmente contribuído como uma nota técnica no site da rOpenSci por [Scott Chamberlain](https://github.com/sckott); você pode ler a versão original [aqui] (https://ropensci.org/technotes/2017/01/05/package-evolution/)._
12
11
```
13
12
14
-
## Philosophy of changes {#philosophy-of-changes}
13
+
## Filosofia das alterações {#philosophy-of-changes}
15
14
16
-
Everyone's free to have their own opinion about how freely parameters/functions/etc. are changed in a library - rules about package changes are not enforced by CRAN or otherwise. Generally, as a library gets more mature, changes to user facing methods (i.e., exported functions in an R package) should become very rare. Libraries that are dependencies of many other libraries are likely to be more careful about changes, and should be.
15
+
Todos são livres para ter sua própria opinião sobre a liberdade com que parâmetros/funções/etc. são alterados em uma biblioteca - as regras sobre alterações de pacotes não são impostas pelo CRAN ou de outra forma. Em geral, à medida que uma biblioteca se torna mais madura, as alterações nos métodos voltados para o usuário (ou seja, funções exportadas em um pacote R) devem se tornar muito raras. As bibliotecas que são dependências de muitas outras bibliotecas provavelmente serão mais cuidadosas com as alterações, e devem ser.
17
16
18
-
## The lifecycle package {#the-lifecycle-package}
17
+
## O pacote de ciclo de vida {#the-lifecycle-package}
19
18
20
-
This chapter presents solutions that do not require the lifecycle package but you might still find it useful.
21
-
We recommend [reading the lifecycle documentation](https://lifecycle.r-lib.org/articles/stages.html).
19
+
Este capítulo apresenta soluções que não requerem o pacote lifecycle, mas que você ainda pode considerar úteis.
20
+
Recomendamos que você [que você leia a documentação do ciclo de vida](https://lifecycle.r-lib.org/articles/stages.html).
## Parâmetros: alteração dos nomes dos parâmetros {#parameters-changing-parameter-names}
24
23
25
-
Sometimes parameter names must be changed for clarity, or some other reason.
24
+
Às vezes, os nomes dos parâmetros precisam ser alterados para maior clareza ou por algum outro motivo.
26
25
27
-
A possible approach is check if deprecated arguments are not missing, and stop providing a meaningful message.
26
+
Uma abordagem possível é verificar se os argumentos obsoletos não estão faltando e parar de fornecer uma mensagem significativa.
28
27
29
28
```r
30
29
foo_bar<-function(x, y) {
@@ -38,7 +37,7 @@ foo_bar(x = 5)
38
37
#> Error in foo_bar(x = 5) : use 'y' instead of 'x'
39
38
```
40
39
41
-
If you want to be more helpful, you could emit a warning but automatically take the necessary action:
40
+
Se quiser ser mais útil, você pode emitir um aviso, mas tomar automaticamente a ação necessária:
42
41
43
42
```r
44
43
foo_bar<-function(x, y) {
@@ -53,21 +52,21 @@ foo_bar(x = 5)
53
52
#> 25
54
53
```
55
54
56
-
Be aware of the parameter `...`. If your function has`...`, and you have already removed a parameter (lets call it`z`), a user may have older code that uses `z`. When they pass in `z`, it's not a parameter in the function definition, and will likely be silently ignored -- not what you want. Instead, leave the argument around, throwing an error if it used.
55
+
Esteja ciente do parâmetro `...`. Se sua função tiver`...` e você já tiver removido um parâmetro (vamos chamá-lo de`z`), um usuário pode ter um código mais antigo que usa `z`. Quando você passa o parâmetro `z` ele não é um parâmetro na definição da função e provavelmente será ignorado silenciosamente - não é o que você deseja. Em vez disso, deixe o argumento por perto, lançando um erro se ele for usado.
57
56
58
-
## Functions: changing function names {#functions-changing-function-names}
57
+
## Funções: alteração de nomes de funções {#functions-changing-function-names}
59
58
60
-
If you must change a function name, do it gradually, as with any other change in your package.
59
+
Se você precisar alterar o nome de uma função, faça-o gradualmente, como em qualquer outra alteração em seu pacote.
61
60
62
-
Let's say you have a function`foo`.
61
+
Digamos que você tenha uma função`foo`.
63
62
64
63
```r
65
64
foo<-function(x) x+1
66
65
```
67
66
68
-
However, you want to change the function name to`bar`.
67
+
No entanto, você deseja alterar o nome da função para`bar`.
69
68
70
-
Instead of simply changing the function name and `foo`no longer existing straight away, in the first version of the package where`bar`appears, make an alias like:
69
+
Em vez de simplesmente alterar o nome da função e `foo`deixar de existir imediatamente, na primeira versão do pacote em que o`bar`aparecer, crie um alias como:
71
70
72
71
```r
73
72
#' foo - add 1 to an input
@@ -79,9 +78,9 @@ foo <- function(x) x + 1
79
78
bar<-foo
80
79
```
81
80
82
-
With the above solution, the user can use either `foo()`or`bar()` -- either will do the same thing, as they are the same function.
81
+
Com a solução acima, o usuário pode usar `foo()`ou`bar()` -- ambos farão a mesma coisa, pois são a mesma função.
83
82
84
-
It's also useful to have a message but then you'll only want to throw that message when they use the old function, e.g.,
83
+
Também é útil ter uma mensagem, mas você só vai querer lançar essa mensagem quando eles usarem a função antiga, por exemplo,
85
84
86
85
```r
87
86
#' foo - add 1 to an input
@@ -96,33 +95,33 @@ foo <- function(x) {
96
95
bar<-function(x) x+1
97
96
```
98
97
99
-
After users have used the package version for a while (with both `foo`and`bar`), in the next version you can remove the old function name (`foo`), and only have`bar`.
98
+
Depois que os usuários tiverem usado a versão do pacote por algum tempo (com ambos os `foo`e`bar`), na próxima versão você poderá remover o nome da função antiga (`foo`), e você terá apenas`bar`.
## Funções: depreciadas e extintas {#functions-deprecate-defunct}
108
107
109
-
To remove a function from a package (let's say your package name is `helloworld`), you can use the following protocol:
108
+
Para remover uma função de um pacote (digamos que o nome do seu pacote seja `helloworld`), você pode usar o seguinte protocolo:
110
109
111
-
-Mark the function as deprecated in package version `x` (e.g., `v0.2.0`)
110
+
-Marque a função como obsoleta na versão do pacote `x` (por exemplo, `v0.2.0`)
112
111
113
-
In the function itself, use `.Deprecated()`to point to the replacement function:
112
+
Na própria função, use `.Deprecated()`para apontar para a função de substituição:
114
113
115
114
```r
116
115
foo<-function() {
117
116
.Deprecated("bar")
118
117
}
119
118
```
120
119
121
-
There's options in`.Deprecated`for specifying a new function name, as well as a new package name, which makes sense when moving functions into different packages.
120
+
Há opções em`.Deprecated`para especificar um novo nome de função, bem como um novo nome de pacote, o que faz sentido quando você move funções para pacotes diferentes.
122
121
123
-
The message that's given by `.Deprecated`is a warning, so can be suppressed by users with`suppressWarnings()`if desired.
122
+
A mensagem que é dada por `.Deprecated`é um aviso, portanto, pode ser suprimida por usuários com`suppressWarnings()`se você desejar.
124
123
125
-
Make a man page for deprecated functions like:
124
+
Crie uma página de manual para funções obsoletas, como:
126
125
127
126
```r
128
127
#' Deprecated functions in helloworld
@@ -138,43 +137,43 @@ Make a man page for deprecated functions like:
138
137
NULL
139
138
```
140
139
141
-
This creates a man page that users can access like ``?`helloworld-deprecated` ``and they'll see in the documentation index. Add any functions to this page as needed, and take away as a function moves to defunct (see below).
140
+
Isso cria uma página de manual que os usuários podem acessar como ``?`helloworld-deprecated` ``e que você verá no índice da documentação. Adicione quaisquer funções a essa página conforme necessário e remova-as quando uma função se tornar obsoleta (veja abaixo).
142
141
143
-
-In the next version (`v0.3.0`) you can make the function defunct (that is, completely gone from the package, except for a man page with a note about it).
142
+
-Na próxima versão (`v0.3.0`), você pode tornar a função extinta (ou seja, completamente fora do pacote, exceto por uma página de manual com uma nota sobre ela).
144
143
145
-
In the function itself, use `.Defunct()`like:
144
+
Na própria função, use `.Defunct()`como:
146
145
147
146
```r
148
147
foo<-function() {
149
148
.Defunct("bar")
150
149
}
151
150
```
152
151
153
-
Note that the message in`.Defunct`is an error so that the function stops whereas`.Deprecated`uses a warning that let the function proceed.
152
+
Observe que a mensagem em`.Defunct`é um erro para que a função pare, enquanto`.Deprecated`usa um aviso que permite que a função continue.
154
153
155
-
In addition, it's good to add `...`to all defunct functions so that if users pass in any parameters they'll get the same defunct message instead of a `unused argument`message, so like:
154
+
Além disso, é bom adicionar `...`a todas as funções extintas para que, se os usuários passarem algum parâmetro, recebam a mesma mensagem de extinção em vez de um `unused argument`assim, por exemplo:
156
155
157
156
```r
158
157
foo<-function(...) {
159
158
.Defunct("bar")
160
159
}
161
160
```
162
161
163
-
Without`...`gives:
162
+
Sem`...`dá:
164
163
165
164
```r
166
165
foo(x=5)
167
166
#> Error in foo(x = 5) : unused argument (x = 5)
168
167
```
169
168
170
-
And with`...`gives:
169
+
E com`...`dá:
171
170
172
171
```r
173
172
foo(x=5)
174
173
#> Error: 'foo' has been removed from this package
175
174
```
176
175
177
-
Make a man page for defunct functions like:
176
+
Faça uma página de manual para funções extintas, como:
178
177
179
178
```r
180
179
#' Defunct functions in helloworld
@@ -189,21 +188,21 @@ Make a man page for defunct functions like:
189
188
NULL
190
189
```
191
190
192
-
This creates a man page that users can access like ``?`helloworld-defunct` ``and they'll see in the documentation index. Add any functions to this page as needed. You'll likely want to keep this man page indefinitely.
191
+
Isso cria uma página de manual que os usuários podem acessar como ``?`helloworld-defunct` ``e que você verá no índice da documentação. Você pode adicionar quaisquer funções a essa página, conforme necessário. Você provavelmente desejará manter essa página de manual indefinidamente.
### Teste de funções obsoletas {#testing-deprecated-functions}
195
194
196
-
You don't have to change the tests of deprecated functions until they are made defunct.
195
+
Você não precisa alterar os testes de funções obsoletas até que elas se tornem obsoletas.
197
196
198
-
-Consider any changes made to a deprecated function. Along with using`.Deprecated`inside the function, did you change the parameters at all in the deprecated function, or create a new function that replaces the deprecated function, etc. Those changes should be tested if any made.
199
-
-Related to above, if the deprecated function is simply getting a name change, perhaps test that the old and new functions return identical results.
200
-
-[`suppressWarnings()`could be used](https://community.rstudio.com/t/unit-testing-of-a-deprecated-function/42837/2)to suppress the warning thrown from`.Deprecated`, but tests are not user facing, so it is not that bad if the warning is thrown in tests, and the warning could even be used as a reminder to the maintainer.
197
+
-Considere todas as alterações feitas em uma função obsoleta. Além de usar`.Deprecated`dentro da função, você alterou os parâmetros na função obsoleta ou criou uma nova função que substitui a função obsoleta, etc.? Essas alterações devem ser testadas, caso você as tenha feito.
198
+
-Em relação ao que foi dito acima, se a função obsoleta estiver apenas recebendo uma alteração de nome, talvez você possa testar se as funções antiga e nova retornam resultados idênticos.
199
+
-[`suppressWarnings()`poderia ser usado](https://community.rstudio.com/t/unit-testing-of-a-deprecated-function/42837/2)para suprimir o aviso lançado pelo`.Deprecated` mas os testes não são voltados para o usuário, portanto, não é tão ruim se o aviso for lançado nos testes, e o aviso pode até ser usado como um lembrete para o mantenedor.
201
200
202
-
Once a function is made defunct, its tests are simply removed.
201
+
Quando uma função se torna extinta, seus testes são simplesmente removidos.
203
202
204
-
## Archiving packages {#archivalguidance}
203
+
## Arquivamento de pacotes {#archivalguidance}
205
204
206
-
Software generally has a finite lifespan, and packages may eventually need to be archived. Archived packages are [archived](https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories)and moved to a dedicated GitHub organization, [ropensci-archive](https://github.com/ropensci-archive). Prior to archiving, the contents of the README file should be moved to an alternative location (such as "README-OLD.md"), and replaced with minimal contents including something like the following:
205
+
O software geralmente tem uma vida útil finita, e os pacotes podem precisar ser arquivados. Os pacotes arquivados são [arquivados](https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories)e movidos para uma organização dedicada do GitHub, [ropensci-archive](https://github.com/ropensci-archive). Antes do arquivamento, o conteúdo do arquivo README deve ser movido para um local alternativo (como "README-OLD.md") e substituído por um conteúdo mínimo, incluindo algo como o seguinte:
207
206
208
207
```md
209
208
# <package name>
@@ -214,18 +213,18 @@ Software generally has a finite lifespan, and packages may eventually need to be
214
213
This package has been archived. The former README is now in [README-old](<link-to-README-old>).
215
214
```
216
215
217
-
The repo status badge should be "unsupported" for formerly released packages, or "abandoned" for former concept or WIP packages, in which case the badge code above should be replaced with:
216
+
O emblema de status do repositório deve ser "unsupported" (sem suporte) para pacotes lançados anteriormente ou "abandoned" (abandonado) para pacotes de conceito anterior ou WIP, caso em que o código do emblema acima deve ser substituído por:
An example of a minimal README in an archived package is in [ropensci-archive/monkeylearn](https://github.com/ropensci-archive/monkeylearn/blob/master/README.md). Once the README has been copied elsewhere and reduced to minimal form, the following steps should be followed:
222
+
Um exemplo de um README mínimo em um pacote arquivado está em [ropensci-archive/monkeylearn](https://github.com/ropensci-archive/monkeylearn/blob/master/README.md). Depois que o LEIAME tiver sido copiado em outro lugar e reduzido à forma mínima, você deverá seguir as etapas a seguir:
224
223
225
-
-[ ]Close issues with a sentence explaining the situation and linking to this guidance.
226
-
-[ ]Archive the repository on GitHub (also under repo settings).
227
-
-[ ]Transfer the repository to[ropensci-archive](https://github.com/ropensci-archive), or request an [rOpenSci staff member](https://ropensci.org/about/#team)to transfer it (you can email`[email protected]`).
224
+
-[ ]Encerre os problemas com uma frase que explique a situação e faça um link para esta orientação.
225
+
-[ ]Arquive o repositório no GitHub (também nas configurações do repositório).
226
+
-[ ]Transfira o repositório para[ropensci-archive](https://github.com/ropensci-archive) ou solicite um [membro da equipe do rOpenSci](https://ropensci.org/about/#team)para transferi-lo (você pode enviar um e-mail para`[email protected]`).
228
227
229
-
Archived packages may be unarchived if authors or a new person opt to resume maintenance. For that please contact rOpenSci. They are transferred to the ropenscilabs organization.
228
+
Os pacotes arquivados podem ser desarquivados se os autores ou uma nova pessoa optarem por retomar a manutenção. Para isso, entre em contato com a rOpenSci. Eles serão transferidos para a organização ropenscilabs.
0 commit comments