Repository navigation
Update APE1 to include procedures for updating APEs - #60
Conversation
First draft ready for discussion on astropy-dev Encourage labeling major changes in APE text
| submitted as a Pull Request. The submission of the Pull Request should | ||
| be announced formally on the astropy-dev list before they are | ||
| accepted. If not already listed, the update champion can add | ||
| themselves to the author list for the APE being updated. When |
There was a problem hiding this comment.
I think it's better to keep the metadata along with the addendum. E.g. keeping the date of its addition, and the authors at the addendum header level
pllim
left a comment
pllim
left a comment
There was a problem hiding this comment.
Given @perrygreenfield originally wrote this, his feedback would be valuable.
Co-authored-by: Brigitta Sipőcz <[email protected]>
Would like to see some changes before accepting
astrofrog
left a comment
astrofrog
left a comment
There was a problem hiding this comment.
I'm on board with the idea but am uncomfortable with changing the top-level metadata such as authors and date accepted. In line with what @bsipocz said I would like to suggest the following: that we simply add e.g.[added 2020-12-22 by Lia Corrales] or [revised 2020-12-22 by Lia Corrales] depending on the kind of change, next to the changes. So if this is a new section, it would come after the section heading, and if the change concerns just a paragraph then we could add that at the end of the paragraph. This would then avoid changing the original APE metadata and preserve the history of modifications.
|
Agreed to keep the header intact, but do think the header should give some sense of the revision history. So, maybe simply adding But absolutely not critical - the comments so far all seem about details of the text, and it would be good to get this in! |
Cadair
left a comment
Cadair
left a comment
There was a problem hiding this comment.
I share opinions about the metadata but otherwise looks good.
eteq
left a comment
eteq
left a comment
There was a problem hiding this comment.
I tried to roll up all the feedback into suggestions, in particular a specific wording on the metadata header changes (a la #60 (comment)). I agree with everyone that we don't want to change the authors/accepted metadata, but I like the idea of the revisions being tracked in the metadata but not inline. I think it'll be confusing to keep track of all the revised lines in the document, since after all, that's what git is for!
|
One other thought that just hit me and @astrofrog in an out-of-band discussion: we should also have the instructions on accepting PRs to include that a new version should be uploaded to Zenodo using Zenodo's fancy versioning feature so that the generic links refer to both versions. But we should do that as a follow-on PR, submitted by whoever accepts this PR, since they will have to do the process anyway! 🤪 |
|
Following discussions within the CoCo, I have updated this APE to suggest a 'minimal' process - basically just make the changes (no annotations), update the author list, and (an idea I had, not discussed with the rest of the CoCo yet) add a 'Previous versions of this APE' with a list of dates/DOIs to access previous published versions. |
|
One caveat to my approval is that I just read the changes effectively starting fresh. I didn't explicitly verify that all the discussions have been resolved, but I'm assuming so at this point. |
| ----------------------- | ||
|
|
||
| author: Perry Greenfield | ||
| author: Perry Greenfield, Lia Corrales, Thomas Robitaille |
There was a problem hiding this comment.
wasn't the conclusion that the addendums get a new metadata header with the new authors rather than rewriting history for the original one?
There was a problem hiding this comment.
Yes indeed, I've implemented that now
efda988 to
aa1dcc1
Compare
|
I realised that there was actually consensus above about having a revised-by metadata line which I think makes things a bit cleaner, so have updated the APE to reflect this. I've now made sure all other discussions were resolved. @eteq - I added some of your wording suggestions so added you as a revision author. @taldcroft - I'm re-requesting your review given the addition of the revised-by header now. |
I'm now an author so dismissing my review
taldcroft
left a comment
taldcroft
left a comment
There was a problem hiding this comment.
This has been reviewed by the Astropy Coordination Committee and approved.
|
I am looking into proposing a modification to APE 1 and I think this change was never issued a DOI. FYI. |
8 participants
I have updated a section of APE1 to include procedures for updating APEs via pull request.
The procedure is much like the creation of APEs, in that one person is expected the "champion" the modification PR with feedback from astropy-dev and similar communication venues. This policy will be useful as we go forward with more formal governance structures, e.g., those outlined in the forthcoming APE-0.