-
Notifications
You must be signed in to change notification settings - Fork 18
/
Copy pathgit-version-control.Rmd
1470 lines (985 loc) · 50.4 KB
/
git-version-control.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
# Git Version Control
The _Bioconductor_ project is maintained in a Git source control
system. Package maintainers update their packages by pushing changes
to their git repositories.
This chapter contains several sections that will cover typical scenarios
encountered when adding and maintaining a Bioconductor package.
## Essential work flow
A minimal workflow is to checkout, update, commit, and push changes to
your repository. Using `BiocGenerics` as an example:
git clone [email protected]:packages/BiocGenerics
cd BiocGenerics
## add a file, e.g., `touch README`
## edit file, e.g., `vi DESCRIPTION`
BiocGenerics$ git commit README DESCRIPTION
BiocGenerics$ git push
This requires that _Bioconductor_ knows the SSH keys you use to
establish your identity.
Two useful commands are
BiocGenerics$ git diff # review changes prior to commit
BiocGenerics$ git log # review recent commits
If the repository is already cloned, the work flow is to make sure
that you are on the 'devel' branch, pull any changes, then introduce
your edits.
BiocGenerics$ git checkout devel
BiocGenerics$ git pull
## add, edit, commit, and push as above
## Where to Commit Changes
New features and bug fixes are introduced on the devel branch of the GIT
repository.
BiocGenerics$ git checkout devel
BiocGenerics$ git pull
## edit 'R/foo.R' and commit on devel
BiocGenerics$ git commit R/foo.R #
[devel c955179] your commit message
1 file changed, 10 insertions(+), 3 deletions(-)
BiocGenerics$ git push
To make more extensive changes see [Fix bugs in devel and release][].
Bug fixes can be ported to the current release branch. Use
`cherry-pick` to identify the commmit(s) you would like to port. E.g.,
for release 3.6, porting the most recent commit to devel
BiocGenerics$ git checkout RELEASE_3_6
BiocGenerics$ git cherry-pick devel
BiocGenerics$ git push
## Checks and version bumps
Each commit pushed to the _Bioconductor_ repository should build and
check without errors or warnings
BiocGenerics$ cd ..
R CMD build BiocGenerics
R CMD check BiocGenerics_1.22.3.tar.gz
Each commit, in either release or devel, should include a bump in the
`z` portion of the `x.y.z` package [versioning scheme][versioning].
Builds occur once per day, and take approximately 24 hours. See the
[build report][devel-software-build-report] for git commits captured in the most recent build
(upper left corner)
## Annotation packages
Traditional Annotation packages are not stored in GIT due to the size of
annotation files. To update an existing Annotation package please send an email
to [email protected]. A member of the Bioconductor team will be in
contact to receive the updated package.
Newer annotation packages can be stored in GIT as it is a requirement to use the
`r BiocStyle::Biocpkg("AnnotationHub")` server hosted data. The larger sized
files are not included directly in the package. To contribute a new Annotation
package please contact [email protected] for guidance and read the
documentation on [Create A Hub Package][].
Currently direct updates to annotation packages, even those stored on git, are
not supported. If you wish to updated an annotation package, make required
changes and push to git.bioconductor.org. Then send an email to
[email protected] or [email protected] requesting the package be propagated.
## Subversion to Git Transition
The essential steps for transitioning from SVN to git are summarized
in
- [New package workflow][]: update your GitHub repository after
package acceptance.
- [Create a new GitHub repository][] for an existing package.
- [Maintain a _Bioconductor_-only repository][] for an existing
package.
### New package workflow
__Goal__: You developed a package in GitHub, following the
_Bioconductor_ new package [Contributions README][tracker] guidelines,
[submitted it to _Bioconductor_](#bioconductor-package-submissions), and your package has been
moderated. As part of moderation process, the package to be reviewed
has been added as a repository on the [_Bioconductor_ git server][git].
During and after the review process, package authors must push changes
that include a **version number 'bump'** to the _Bioconductor_ git
repository. This causes the package to be built and checked on Linux,
macOS, and Windows operating systems, and forms the basis for the
review process.
In this document, package authors will learn best practices for
pushing to the _Bioconductor_ git repository.
1. **SSH keys**. As part of the initial moderation step,
_Bioconductor_ will use SSH 'public key' keys available in
`https://github.com/<your-github-id>.keys`.
After the review process is over, additional SSH keys can be added
and contact information edited using the [BiocCredentials
application][].
1. **Configure the "remotes" of your local git repository**. You will need
to push any future changes to your package to the _Bioconductor_ git
repository to issue a new build of your package.
Add a remote named `upstream` to your package's local git
repository using:
git remote add upstream [email protected]:packages/<YOUR-REPOSITORY-NAME>.git
Check that you have updated the remotes in your repository; you'll
see an `origin` remote pointing to `github.com`, and an `upstream` remote
pointing to `bioconductor.org`
$ git remote -v
origin <link to your github> (fetch)
origin <link to your github> (push)
upstream [email protected]:packages/<YOUR-REPOSITORY-NAME>.git (fetch)
upstream [email protected]:packages/<YOUR-REPOSITORY-NAME>.git (push)
NOTE: As a package developer, you must use the SSH protocol (as in
the above command) to gain read/write access to your package in the
_Bioconductor_ git repository.
1. **Add and commit changes to your local repository**. During the
review process you will likely need to update your package. Do this
in your local repository by first making sure your repository is
up-to-date with your `github.com` and `git.bioconductor.org`
repositories.
git fetch --all
## merge changes from Bioc (upstream remote at [email protected])
git merge upstream/devel
## merge changes from GitHub (origin remote)
git merge origin/devel
**Note**. If your GitHub default branch is `main`, replace `devel` with
`main`:
## merge changes from GitHub (origin remote)
git merge origin/main
Make changes to your package devel branch and commit them to your
local repository
git add <files changed>
git commit -m "<informative commit message>"
1. **'Bump' the package version**. Your package version number is in
the format 'major.minor.patch'. Initial package submissions should have
a version number of `0.99.0`, as indicated by the `Version` field in the
`DESCRIPTION` file. Increment the `patch` version number by 1, e.g., to
`0.99.1`, `0.99.2`, ..., `0.99.9`, `0.99.10`, ...
Bumping the version number before pushing is essential. It ensures
that the package is built across platforms.
Remember to add and commit these changes to your local repository.
1. **Push changes to the Bioconductor and GitHub repositories**. Push
the changes in your local repository to the _Bioconductor_ and
GitHub repositories.
## push to BioC (upstream remote at [email protected])
git push upstream devel
## push to GitHub (origin remote)
git push origin devel
**Note**. If your GitHub default branch is `main`, replace `devel` with
`main`:
## push to Bioc (upstream remote at [email protected])
git push upstream main:devel
## push to GitHub (origin remote)
git push origin main
1. **Check the updated build report**. If your push to
git.bioconductor.org included a version bump, you'll receive an
email directing you to visit your issue on github.com,
`https://github.com/Bioconductor/Contributions/issues/`; a comment
is also posted on the issue indicating that a build has started.
After several minutes a second email and comment will indicate that
the build has completed, and that the build report is
available. The comment includes a link to the build report. Follow
the link to see whether further changes are necessary.
1. See other scenarios for working with _Bioconductor_ and GitHub repositories, in particular:
- [Maintain GitHub and _Bioconductor_ repositories][].
- [Fix bugs in devel and release][].
- [Resolve merge conflicts][mergeconflict].
### Create a new GitHub repository for an existing _Bioconductor_ package {#maintain-github-bioc}
__Goal:__ As a maintainer, you'd like to create a new GitHub
repository for your existing _Bioconductor_ repository, so that your
user community can engage in the development of your package.
1. [Create a new GitHub account][] if you don't have one.
1. Set up remote access to GitHub via SSH or Https. Please check
[which-remote-url-should-i-use][] and
[add your public key to your GitHub account][].
1. Once you have submitted your keys, you can login to the
[BiocCredentials application][] to check if the correct
keys are on file with _Bioconductor_.
1. [Create a new GitHub repo][] on your account, with the name
of the existing _Bioconductor_ package.
We use "BiocGenerics" as an example for this scenario.
```{r,echo=FALSE}
knitr::include_graphics("images/create_repo.png")
```
After pressing the 'Create repository' button, __ignore__ the
instructions that GitHub provides, and follow the rest of this
document.
1. On your local machine, clone the empty repository from GitHub.
Use `https` URL (replace `<developer>` with your GitHub username)
git clone https://github.com/<developer>/BiocGenerics.git
or `SSH` URL
git clone [email protected]:<developer>/BiocGenerics.git
1. Add a remote to your cloned repository.
Change the current working directory to your local repository
cloned in the previous step.
cd BiocGenerics
git remote add upstream [email protected]:packages/BiocGenerics.git
1. Fetch content from remote upstream,
git fetch upstream
1. Merge upstream with origin's devel branch,
git merge upstream/devel
__NOTE:__ If you have the error `fatal: refusing to merge
unrelated histories`, then the repository cloned in step 4 was not
empty. Either clone an empty repository, or see
[Sync existing repositories][].
1. Push changes to your origin devel,
git push origin devel
__NOTE:__ Run the command `git config --global push.default
matching` to always push local branches to the remote branch of
the same name, allowing use of `git push origin` rather than `git
push origin devel`.
1. (Optional) Add a branch to GitHub,
## Fetch all updates
git fetch upstream
## Checkout new branch RELEASE_3_6, from upstream/RELEASE_3_6
git checkout -b RELEASE_3_6 upstream/RELEASE_3_6
## Push updates to remote origin's new branch RELEASE_3_6
git push -u origin RELEASE_3_6
1. Check your GitHub repository to confirm that the `devel` (and
optionally `RELEASE_3_6`) branches are present.
1. Once the GitHub repository is established follow
[Push to GitHub and _Bioconductor_][] to maintain your repository
on both GitHub and Bioconductor.
### Maintain a _Bioconductor_-only repository for an existing package {#maintain-bioc-only}
__Goal:__ Developer wishes to maintain their _Bioconductor_ repository
without using GitHub.
#### Clone and setup the package on your local machine.
1. Make sure that you have `SSH` access to the _Bioconductor_
repository; be sure to [submit your SSH public key][BiocCredentials application] or
github id to _Bioconductor_.
1. Clone the package to your local machine,
git clone [email protected]:packages/<ExamplePackage>
__NOTE:__ If you clone with `https` you will NOT get read+write
access.
1. View existing remotes
git remote -v
which will display
origin [email protected]:packages/<ExamplePackage>.git (fetch)
origin [email protected]:packages/<ExamplePackage>.git (push)
This indicates that your git repository has only one remote
`origin`, which is the _Bioconductor_ repository.
1. In other work flows, the `origin` remote has been renamed to
`upstream`. It may be convenient to make this change to your own
repository
git remote rename origin upstream
and confirm that `git remote -v` now associates the `upstream`
repository name with `[email protected]`.
#### Commit changes to your local repository
1. Before making changes to your repository, make sure to `pull`
changes or updates from the _Bioconductor_ repository. This is
needed to avoid conflicts.
git pull
1. Make the required changes, then `add` and `commit` your changes to
your `devel` branch.
git add <files changed>
git commit -m "My informative commit message"
1. (Alternative) If the changes are non-trivial, create a new branch
where you can easily abandon any false starts. Merge the final
version onto `devel`
git checkout -b feature-my-feature
## add and commit to this branch. When the change is complete...
git checkout devel
git merge feature-my-feature
#### Push your local commits to the _Bioconductor_ repository
1. Push your commits to the _Bioconductor_ repository to make them
available to the user community.
Push changes to the `devel` branch using:
git checkout devel
git push upstream devel
Make sure there is a valid version bump for the changes to propagate to users.
#### (Optional) Merge changes to the current release branch
Merging devel into release branch should be avoided. Select bug fixes should be
cherry-picked from devel to release. See section [Bug Fixes in Release and Devel](#bug-fix-in-release-and-devel)
## More scenarios for repository creation
- [Sync an existing GitHub repository][Sync existing repositories] with _Bioconductor_.
- [Create a local repository][] for private use.
### Sync an existing GitHub repository with _Bioconductor_ {#sync-existing-repositories}
__Goal:__ Ensure that your local, _Bioconductor_, and GitHub
repositories are all in sync.
1. Clone the GitHub repository to a local machine. Change into the
directory containing the repository.
1. Configure the "remotes" of the GitHub clone.
git remote add upstream [email protected]:packages/<YOUR-REPOSITORY>.git
1. Fetch updates from all (_Bioconductor_ and GitHub) remotes. You may
see "warning: no common commits"; this will be addressed after
resolving conflicts, below.
git fetch --all
1. Make sure you are on the devel branch.
git checkout devel
1. Merge updates from the GitHub (`origin`) remote
git merge origin/devel
1. Merge updates from the _Bioconductor_ (`upstream`) remote
git merge upstream/devel
Users of git version >= 2.9 will see an error message ("fatal:
refusing to merge unrelated histories") and need to use
git merge --allow-unrelated-histories upstream/devel
1. [Resolve merge conflicts][mergeconflict] if necessary.
1. After resolving conflicts and committing changes, look for duplicate
commits (e.g., `git log --oneline | wc` returns twice as many
commits as in SVN) and consider following the steps to
[force Bioconductor `devel` to GitHub `devel`][force-bioc-to-github].
1. Push to both _Bioconductor_ and GitHub repositories.
git push upstream devel
git push origin devel
1. Repeat for the release branch, replacing `devel` with the name of
the release branch, e.g., `RELEASE_3_6`. It may be necessary to
create the release branch in the local repository.
git checkout RELEASE_3_6
git merge upstream/RELEASE_3_6
git merge origin/RELEASE_3_6
git push upstream RELEASE_3_6
git push origin RELEASE_3_6
NOTE: If you are syncing your release branch for the first time,
you have to make a local copy of the `RELEASE_X_Y` branch, by
git checkout -b <RELEASE_X_Y> upstream/<RELEASE_X_Y>
Following this one time local checkout, you may switch between
`RELEASE_X_Y` and `devel` with `git checkout <RELEASE_X_Y>`. If you do
not use the command to get a local copy of the release branch, you
will get the message,
(HEAD detached from origin/RELEASE_X_Y)
Remember that only `devel` and the current release branch of
_Bioconductor_ repositories can be updated.
### Create a local repository for private use {#create-local-repository}
__Goal:__ A user (not the package developer) would like to modify
functions in a package to meet their needs. There is no GitHub
repository for the package.
1. Clone the package from the _Bioconductor_ repository. As an end
user, you do not have write access to the repository, so use the
__https__ protocol
git clone https://[email protected]/packages/<ExamplePackage>
1. Make changes to your local repository. Commit the changes to your
local repository. A best practice might modify the changes in a new
branch
git checkout -b feature-my-feature
## modify
git commit -a -m "feature: a new feature"
and then merge the feature onto the branch corresponding to the
release in use, e.g.,
git checkout <RELEASE_X_Y>
git merge feature-my-feature
1. Rebuild (to create the vignette and help pages) and reinstall the
package in your local machine by running in the parent directory of
_ExamplePackage_
R CMD build ExamplePackage
R CMD INSTALL ExamplePackage_<version.number>.tar.gz
1. The package with the changes should be available in your local _R_
installation.
## Scenarios for code update
- [Pull upstream changes][] (e.g., introduced by the core team)
- [Push to GitHub and _Bioconductor_][] repositories
- [Resolve merge conflicts][mergeconflict]
- [Abandon changes][]
- [Fix bugs in devel and release][]
- [Bug fixes due to API changes][]
- [Resolve duplicate commits][]
### Pull upstream changes
__Goal:__ Your _Bioconductor_ repository has been updated by the core
team. You want to fetch these commits from _Bioconductor_, merge them
into your local repository, and push them to GitHub.
__NOTE:__ It is always a good idea to fetch updates from
_Bioconductor_ before making more changes. This will help prevent
merge conflicts.
These steps update the `devel` branch.
1. Make sure you are on the appropriate branch.
git checkout devel
1. Fetch content from _Bioconductor_
git fetch upstream
1. Merge upstream with the appropriate local branch
git merge upstream/devel
Get help on [Resolve merge conflicts][mergeconflict] if these occur.
1. If you also maintain a GitHub repository, push changes to GitHub's
(`origin`) `devel` branch
git push origin devel
To pull updates to the current `RELEASE_X_Y` branch, replace `devel`
with `RELEASE_X_Y` in the lines above.
See instructions to [Sync existing repositories][] with
changes to both the _Bioconductor_ and GitHub repositories.
### Push to GitHub and _Bioconductor_ repositories {#push-to-github-bioc}
__Goal:__ During everyday development, you commit changes to your
local repository `devel` branch, and wish to push these commits to
both GitHub and _Bioconductor_ repositories.
__NOTE:__ See [Pull upstream changes][] for best practices before
committing local changes.
1. We assume you already have a GitHub repository with the right setup
to push to _Bioconductor_'s git server
([email protected]). If not please see FAQ's on how to get
access and follow instructions to
[Maintain GitHub and _Bioconductor_ repositories][]. We use a clone
of the `BiocGenerics` package in the following example.
1. To check that remotes are set up properly, run the command inside
your local machine's clone.
git remote -v
which should produce the result (where <developer> is your GitHub
username):
origin [email protected]:<developer>/BiocGenerics.git (fetch)
origin [email protected]:<developer>/BiocGenerics.git (push)
upstream [email protected]:packages/BiocGenerics.git (fetch)
upstream [email protected]:packages/BiocGenerics.git (push)
1. Make and commit changes to the `devel` branch
git checkout devel
## edit files, etc.
git add <name of file changed>
git commit -m "My informative commit message describing the change"
1. (Alternative) When changes are more elaborate, best practice is to
use a local branch for development.
git checkout devel
git checkout -b feature-my-feature
## multiple rounds of edit, add, commit
Merge the local branch to devel when the feature is 'complete'.
git checkout devel
# Pull upstream changes before merging
# http://bioconductor.org/developers/how-to/git/pull-upstream-changes/
git merge feature-my-feature
1. Push updates to GitHub's (`origin`) `devel` branch
git push origin devel
1. Next, push updates to _Bioconductor_'s (`upstream`) `devel` branch
git push upstream devel
1. Confirm changes, e.g., by visiting the GitHub web page for the repository.
### Resolve merge conflicts {#resolve-merge-conflicts}
__Goal:__ Resolve merge conflicts in branch and push to GitHub and
_Bioconductor_ repositories.
1. You will know you have a merge conflict when you see something like
this:
git merge upstream/devel
Auto-merging DESCRIPTION
CONFLICT (content): Merge conflict in DESCRIPTION
Automatic merge failed; fix conflicts and then commit the result
This merge conflict occurs when the package developer makes a
change, and also a collaborator or a _Bioconductor_ core team
member makes a change to the same file (in this case the
`DESCRIPTION` file).
How can you avoid this? [Pull upstream changes][] before
committing any changes. In other words, `fetch` and `merge` remote
branches before a `push`.
1. If in spite of this you have conflicts, you need to fix them. See
which file has the conflict,
git status
This will show you something like this:
On branch devel
Your branch is ahead of 'origin/devel' by 1 commit.
(use "git push" to publish your local commits)
You have un-merged paths.
(fix conflicts and run "git commit")
(use "git merge --abort" to abort the merge)
Un-merged paths:
(use "git add <file>..." to mark resolution)
both modified: DESCRIPTION
no changes added to commit (use "git add" and/or "git commit -a")
1. Open the file in your favorite editor. Conflicts look like:
<<<<<<< HEAD
Version: 0.23.2
=======
Version: 0.23.3
>>>>>>> upstream/devel
Everything between `<<<<` and `=====` refers to HEAD, i.e your
current change. And everything between `=====` and `>>>>>` refers
to the `remote/branch` shown there, i.e `upstream/devel`.
You want to keep the most accurate change, by deleting what is
necessary. In this case, keep the latest version:
Version: 0.23.3
1. Add and commit the file as you would any other change.
git add DESCRIPTION
git commit -m "Fixed conflicts in version change"
1. Push to both your GitHub and _Bioconductor_ repositories,
git push origin devel
git push upstream devel
#### Extra Resources
[Resolving a merge conflict using command line][]
[Based on: Resolving a merge conflict][]
<iframe width="560" height="315" src="https://www.loom.com/embed/03e20ac00992408aadae33a7b7b3384d" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
### Abandon changes
__Goal:__ You want to start fresh after failing to resolve conflicts
or some other issue. If you intend to go nuclear, please contact the
[email protected] mailing list.
#### Force _Bioconductor_ `devel` to GitHub `devel`
One way you can ignore your work and make a new branch is by replacing
your local and GitHub repository `devel` branch with the
_Bioconductor_ `devel` branch.
__Note__: This works only if you haven't pushed the change causing the
issue to the _Bioconductor_ repository.
__Note__: Any references to commits on current devel (e.g., in GitHub
issues) will be invalidated.
1. Checkout a new branch, e.g., `devel_backup`, with tracking set to
track the _Bioconductor_ `devel` branch `upstream/devel`.
git checkout -b devel_backup upstream/devel
1. Rename the branches you currently have on your local
machine. First, rename `devel` to `devel_deprecated`. Second,
rename `devel_backup` to `devel`. This process is called the
classic __Switcheroo__.
git branch -m devel devel_deprecated
git branch -m devel_backup devel
1. You will now have to "force push" the changes to your GitHub
(`origin`) `devel` branch.
git push -f origin devel
1. __(Optional)__ If you have commits on your `devel_deprecated`
branch that you would like ported on to your new `devel`
branch. Git has a special feature called `cherry-pick`
Take a look at which commit you want to cherry-pick on to the new
devel branch, using `git log devel_deprecated`, copy the correct
commit id, and use:
git cherry-pick <commit id>
Push these cherry-picked changes to GitHub and _Bioconductor_
repositories.
#### Reset to a previous commit
If you find yourself in a place where you want to abandon changes
__already committed__ to _Bioconductor_ or GitHub, use `reset` to undo
the commits on your local repository and `push -f` to force the
changes to the remotes. Remember that the `HEAD` commit id is the most
recent __parent__ commit of the current state of your local
repository.
git reset --hard <commit id>
Example:
git reset --hard e02e4d86812457fd9fdd43adae5761f5946fdfb3
HEAD is now at e02e4d8 version bump by bioc core
To make the changes permanent, you will then need to push the changes
to GitHub, and then email the Bioconductor core team to force push to
the repository on Bioconductor.
## You
git push -f origin
Bioconductor core team will do the rest after you email.
#### Delete your local copy and GitHub repo, because nothing is working
__CAUTION: These instructions come with many disadvantages. You have
been warned.__
1. Delete your local repository, e.g., `rm -rf BiocGenerics`
1. Delete (or rename) your GitHub repository.
1. [Maintain GitHub and _Bioconductor_ repositories][] for an existing
_Bioconductor_ repository, then [Pull upstream changes][].
##### Disadvantages of going "nuclear"
1. You will lose all your GitHub issues
1. You will lose your custom collaborator settings in GitHub.
1. You will lose any GitHub-specific changes.
### Fix bugs in `devel` and `release` {#bug-fix-in-release-and-devel}
__Goal:__ When a bug is present in both the release and devel branches of
Bioconductor, a maintainer will have to introduce a patch in the default
git branch and in the current release branch (e.g., `RELEASE_3_14`).
1. First [Sync existing repositories][].
git fetch --all
git checkout devel
git merge upstream/devel
git merge origin/devel
git checkout <RELEASE_X_Y>
git merge upstream/<RELEASE_X_Y>
git merge origin/<RELEASE_X_Y>
1. On your local machine, be sure that you are on the `devel` branch.
git checkout devel
Make the changes needed to fix the bug and add the modified files
to the commit. Remember to bump the version number in the `DESCRIPTION` file
__in a separate commit__. Only bug-fix changes should be introduced in this
commit.
git add <files changed>
Commit the modified files. It is helpful to tag the commit message with "bug
fix".
git commit -m "bug fix: my bug fix"
Bump the version of the package by editing the `Version` field in the
`DESCRIPTION` and commit the change __in a separate commit__. This allows to
only `cherry-pick` the bug correction and avoid version number conflicts with
the Bioconductor branches when/if the bug fixes are ported to release.
## after version bump
git add DESCRIPTION
git commit -m "version bump in devel"
1. (Alternative) If the changes are non-trivial i.e., with multiple commits,
create a new branch where you can easily abandon any false starts.
git checkout devel
git checkout -b bugfix-my-bug
## add and commit to this branch to fix the bug
Merge the final version of the branch into the default branch.
git checkout devel
git merge bugfix-my-bug
1. Switch to the release branch and `cherry-pick` the commit hash or range of
hashes from the default branch that correspond to the bug fix (more examples
in `git cherry-pick --help`). Remember to edit the `DESCRIPTION` file to
update the release version of the package according to _Bioconductor_'s
[version numbering scheme][versioning].
git checkout <RELEASE_X_Y>
## example hash from git log: 2644710
git cherry-pick <hash>
## Bump the version and commit the change
git add DESCRIPTION
git commit -m "version bump in release"
__NOTE__: If you are patching your release for the first time, you have to
make a local copy of the RELEASE_X_Y branch with
git checkout -b <RELEASE_X_Y> upstream/<RELEASE_X_Y>
Following this one time local checkout, you may switch between RELEASE_X_Y
and devel with `git checkout <RELEASE_X_Y>`. If you do not use the command
to get a local checkout of the release branch, you will get the message:
(HEAD detached from origin/RELEASE_X_Y)
1. Push your changes to both the GitHub and _Bioconductor_ `devel`
and `<RELEASE_X_Y>` branches. Make sure you are on the correct
branch on your local machine.
For the `devel` branch,
git checkout devel
git push upstream devel
git push origin devel
For the `release` branch,
git checkout <RELEASE_X_Y>
git push upstream <RELEASE_X_Y>
git push origin <RELEASE_X_Y>
* See the video tutorial here:
<iframe width="568" height="315" src="https://www.loom.com/embed/37525f9ddf434c91b11e8112db46818b" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
### Bug fixes due to API changes {#bug-fixes-due-to-api-changes}
Packages that make use of web APIs will need to be updated when there are
significant API changes. This is a common occurrence with Bioconductor packages
that use REST APIs, e.g., `UniProt.ws`, `AnVIL`, etc. To provide a smooth
experience for users, it is important to update the package as soon as possible.
#### Minor API changes
The steps to apply bug fixes due to API changes are similar to the steps for
fixing bugs in the `devel` and `release` branches. The main difference is that
the bug may be due to minor API issues, certificate issues, API version issues,
etc. The maintainer can readily update the R package to adapt to the new API.
Note that the functionality of the package largely remains the same.
#### Major API changes
It may be possible that an organization's API changes are not backwards
compatible and that they do not provide the same functionality for the existing
Bioconductor package to remain functional. In such case, it is recommended to
contact the organization that maintains the API to get more information about
the changes and to request a backward compatible API, if possible. When API
changes do not provide a similar functionality to that of the R package, the
package maintainer may need to submit a new package that works with the new API
and to deprecate the old package.
### Resolve Duplicate Commits
__Goal:__ You want to get rid of the duplicate (or triplicate) commits
in your git commit history.
Before you begin [Update your package][mergeconflict] to the existing version on
Bioconductor.
#### Steps:
1. **IMPORTANT** Make a backup of the branch with duplicate commits,
call this `devel_backup` (or `RELEASE_3_7_backup`). The name of
the back up branch should be identifiable and specific to the
branch you are trying to fix (i.e if you want to fix the *devel*
branch or some `<RELEASE_X_Y>` branch).
On devel, (make sure you are on devel by `git checkout devel`)
git branch devel_backup
2. Identify the commit from which the duplicates have
originated. These commits are more often than not, `merge` commits.
3. Reset your branch to the commit *before* the merge commit.
git reset —hard <commit_id>
4. Now cherry pick your commits from the `devel_backup` branch.
git cherry-pick <commit_id>
a. The commits you cherry-pick should be only 1 version of the
duplicate commit, i.e don’t cherry-pick the same commit twice.
b. Include the branching and version bump commits in your
cherry-pick. Make the package history look as normal as possible.
5. (Optional) In some cases, there are conflicts you need to fix for
the cherry-pick to succeed. Please read the documentation on how
to [resolve conflicts][mergeconflict]
6. Finally, you would need to contact the bioc-devel mailing list to
reach the Bioconductor core team to sync your repository with the
version on Bioconductor. This is not possible as `--force` pushes
which alter the git timeline are not possible for maintainers.
#### How to check if your package has duplicate commits
One way is to check the log. You should see the same commit message
with the same changes, but with a different commit ID, if you try
git log
or
git log --oneline
#### Script to detect duplicate commits
Run this script written in python to [detect duplicate commits][]
which are specific to Bioconductor repositories.
Usage example:
python detect_duplicate_commits.py /BiocGenerics 1000
python detect_duplicate_commits.py <path_to_package> <number of commits to check>'
## Github scenarios
- [Add collaborators and use Github social coding features](#add-collaborators-and-leverage-github-features).
- [Change Package Maintainer](#change-maintainer)
- [Remove Large Data Files and clean git tree](#remove-large-data-files-and-clean-git-tree)