Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Releases md #20

Merged
merged 8 commits into from
Jul 2, 2020
Merged

Releases md #20

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
bae9cdd
Add releases.md guidelines
hansvancalster Jun 9, 2020
5b13533
Update readme and contributing guidelines
hansvancalster Jun 9, 2020
b2bb0e8
Fix version number
hansvancalster Jun 10, 2020
93ce83a
Improve workflow for docx
hansvancalster Jun 10, 2020
59e2aef
Address review comments
hansvancalster Jun 10, 2020
87af53d
Add example structure repo NEWS.md
hansvancalster Jun 10, 2020
85933bd
Improve explanation version number
hansvancalster Jun 12, 2020
c5eef28
Add an example
hansvancalster Jun 12, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 13 additions & 12 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ This website will host all approved and published versions of all protocols.

## Workflow

The workflow is as follows for a _new_ protocol:
The workflow is as follows for a **new** protocol:

1. make sure your local clone of the remote repository is up to date:
1. with the master branch checked out, press the pull button in the Git pane
Expand Down Expand Up @@ -73,23 +73,26 @@ The workflow is as follows for a _new_ protocol:
![](src/management/pr-on-github-4.png)

1. If the reviewers raise concerns, changes can be made to the protocol that address these concerns (stage, commit, push)
1. When all reviewers have given their approval, the repo admin:
1. adds tags with definitive version numbers to the YAML header
1. updates the repo NEWS.md file
1. and merges the PR to the master
1. When all reviewers have given their approval, the **repo admin** needs to do some necessary admin tasks before merging [see RELEASES.md](RELEASES.md)
1. The GitHub protocols repo is setup in such a way that branches that are merged in the master branch will be deleted automatically.


For an _update_ of an existing protocol all steps are the same, except for:
For an **update** of an existing protocol all steps are the same, except for:
Copy link
Member

@florisvdh florisvdh Jun 11, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A further idea for the protocolhelper package, to start updating an existing protocol? A function that creates and checks out a new branch (protocol-specific), branching off from origin/master (even if one has not checked out master) after fetching origin/master. And also it adds ".dev" to the version number. No auto-committing though, but perhaps staging of the latter. It would just need the protocol code as an input.

Something like:

protocol_code <- "string-by-user" # check if it exists

And then this git workflow, wrapped in system() or mimicked by git2r:

git fetch origin master  # 'origin' could also be generalized to take the first line of the output of 'git remote'
git branch protocol_code origin/master # make the branch
git push -u origin protocol_code:protocol_code # push the branch
git checkout protocol_code # to be put at the end because it is not a fail-safe command (it may error because of unclean working directory)

Plus the adding of .dev (without committing, but perhaps already staged (git add X)).

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

idemdito see inbo/protocolhelper#27

Copy link
Collaborator Author

@hansvancalster hansvancalster Sep 8, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The workflow now mentions the use of checklist::new_branch() (currently only in the renv-setup branch) which deals with most steps (except the final step) listed here. So I think we can just use that, possibly wrapped into a protocolhelper function to include the final step.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds like a good idea!

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ThierryO after checking the code of checklist::new_branch I noticed that https-protocol to talk to GitHub is not supported. So I guess only SSH is supported. That asks quite a lot of confusing setup-steps from often rather inexperienced Rusers who want to contribute to the protocolsource repo. Is this design decision fixed or can https be allowed. I can write an issue or a PR if I understand the code.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After reading this, it leaves me doubting a little about the preference for SSH.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Several NARA colleagues are working with ssh for the latest two years now. So far, only one intervention needed. Due to somebody with a new computer.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I followed the steps (and even wrote a vignette for checklist with all steps), but when I try checklist::new_branch() (within my local clone of the checklist package I want to make a branch to commit the vignette), it fails with this error:

Error in fetch(repo, "origin", verbose = verbose) : 
  Error in 'git2r_remote_fetch': error authenticating: failed connecting agent

This happens inside checklist::clean_git(). I have set git remote set-url origin [email protected]:inbo/checklist.git.

I have no clue what I did wrong. On the other hand, I think issues such as these can be avoided by switching git2r functions to the equivalent gert functions which has automatic authentication (and which would also allow both SSH and HTTPS).

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Switching for git2r to gert is a major change. Something I cannot do on short notice. I'm willing to accept a PR .

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I might give it a try, but it will also take some time...


- you don't need `protocolhelper::create_sfp()`
- the creation of the new branch can (re-)use the protocol-code of the existing protocol
- after review is finished, the protocol-specific `NEWS.Rmd` should be updated to document the substantive changes between the updated version of the previous version.

For adding a pre-existing version of a protocol that was written in `docx` format, follow the steps to create a new protocol, except in the second step:
For adding a **pre-existing version of a protocol that was written in `docx` format**, follow the steps to create a new protocol, except in the second step:

- a subject-matter specialist uses `protocolhelper::create_sfp()` to convert the `docx` protocol to Rmarkdown files. See section [From an existing docx protocol](#from-an-existing-docx-protocol).
- use the protocol-code from the pre-existing `docx` protocol to create a new branch and continue the steps outlined for a new protocol.
- use the protocol-code from the pre-existing `docx` protocol to create a new branch
- in case the chapter titles and Rmarkdown file names differ from the template, change them so they comply with the current template:
- go to [templates](https://github.com/inbo/protocolhelper/tree/master/inst/rmarkdown/templates)
- navigate to the template that you need and then navigate to the skeleton folder
- inspect the Rmarkdown file names and chapter titles
- the file `skeleton.Rmd` should be read as `index.Rmd`
- continue the steps outlined for a new protocol.

## Starting a new protocol with the aid of protocolhelper functions

Expand All @@ -109,14 +112,13 @@ create_sfp(title = "Klassieke vegetatieopname in een proefvlak aan de hand van v
date = "2016-07-19",
reviewers = "Hans Van Calster, Lieve Vriens, Jan Wouters, Wouter Van Gompel, Els Lommelen",
file_manager = "Hans Van Calster",
revision = "1.1.0.9000",
theme = "vegetation",
language = "nl",
from_docx =
file.path(path_to_from_docx,
"SVP_401_VegetatieOpnamePV_Terrestrisch_v1.1.docx"),
protocol_number = "401",
render = TRUE)
render = FALSE)
```


Expand All @@ -133,12 +135,11 @@ create_sfp(title = "titel van het protocol",
date = "`r Sys.Date()`",
reviewers = "Voornaam Naam, ...",
file_manager = "Voornaam Naam",
revision = "0.0.0.9000",
theme = "vegetation",
language = "nl",
from_docx = NULL,
protocol_number = NULL,
render = TRUE)
render = FALSE)
```


Expand Down
12 changes: 11 additions & 1 deletion NEWS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1,11 @@
<!--One entry for each release describing the generic changes since the previous release.-->
<!--One entry for each release describing the generic changes since the previous release.
e.g. (sort most recent first)

- 2020.03
- sfp-403_shorttitle_nl (first version)
- sfp-403_shorttitle_en (first version)
- 2020.02
- sfp-402_shorttitle_nl (update)
- 2020.01
- sfp-402_shorttitle_nl (first version)
-->
9 changes: 6 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,8 +53,8 @@ A release will also trigger the `protocols-website` to update the rendered versi
Tags are associated to each GitHub release.
To identify protocols and differentiate between different versions of protocols, we use two types of tags: a general tag and a specific tag.

The general tag is of the form `protocols-YYYY.number`.
The specific tag is of the form `protocol-code-YYYY.number` (see [protocol-code](#protocol-code) and [version number](#version-number)).
The general tag is of the form `protocols-YYYY.NN`.
The specific tag is of the form `protocol-code-YYYY.NN` (see [protocol-code](#protocol-code) and [version number](#version-number)).

These tags serve several purposes:

Expand Down Expand Up @@ -101,9 +101,12 @@ In case of thematic protocols, the first digit of the protocol-number correspond

### Version number

The version number is of the form `YYYY.number`. `YYYY` indicates the year in which the protocol was released. The `number` indicates the order of release within that year.
The version number is of the form `YYYY.NN`. `YYYY` indicates the year in which the protocol was released. The `NN` is a number that indicates the order of release within that year (starting with 01).
hansvancalster marked this conversation as resolved.
Show resolved Hide resolved
The same version of a protocol may or may not be available in multiple languages (see [Folder and filename syntaxis](#folder-and-filename-syntaxis) and [Translations of protocols](CONTRIBUTING.md#translations-of-protocols)).

The version number is protocol-*aspecific* by definition, i.e. it spans the whole protocols repository (e.g. sfp-401 version `2020.02` will be followed by sfp-401 version `2020.04` if sfp-401 was not updated in the `protocols-2020.03` release).



### Dependencies

Expand Down
20 changes: 20 additions & 0 deletions RELEASES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Creating a new release (guidelines for repo-admins)

After review of a protocol-branch and before each release the following steps are necessary:


1. with the protocol-branch checked-out:
1. bump the version number in the `index.Rmd` yaml section from `yyyy.nn.dev` to `YYYY.NN`. Some examples:
- a new protocol added in 2020 that was released in 2020 (fifth release in that year): `2020.00.dev` to `2020.05`
- an update of the `2020.05` protocol in 2021 (first release in that year): `2020.05.dev` to `2021.01`
hansvancalster marked this conversation as resolved.
Show resolved Hide resolved
- an update of the `2020.02` version of a protocol in the same year (fourth release in that year): `2020.02.dev` to `2020.04`
1. update the `.zenodo.json` file:
- add new authorships
1. update the repo `NEWS.md` file
1. merge the branch to the master and add general and specific tags (see [release model](README.md#release-model)):
1. general tag: `protocols-YYYY.NN`
1. specific tag: `protocol-code-YYYY.NN`
Comment on lines +14 to +16
Copy link
Member

@florisvdh florisvdh Jun 11, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

An idea for the protocolhelper package, because this step, and step 1 (version number update) is prone to errors? I.e. one or more functions to:

  • determine and print the next protocols tag
  • determine and print the next protocol-specific tag(s), i.e. based on the occurrence of dev version(s) in the working directory of current checked out branch
  • (optionally:) bump version number of the involved protocol(s) accordingly, and return message(s) on this

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good ideas. I've made an issue of your comment inbo/protocolhelper#27

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in 65687c6

1. Check if continuous integration proceeded without problems
1. Make a GitHub release from the general tag
1. Check success of publication steps at protocols.inbo.be and at Zenodo (records both source and rendered)

Binary file modified src/management/protocols-gitflow-model.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.