search

ICPI / DIV

Organizational Material
10 stars 2 forks source link

Naming Conventions for Files and Version Control #24

Closed imujawar closed 6 years ago

imujawar commented 6 years ago

2017_11_06_DIV_Name_Conv_IM.docx

achafetz commented 6 years ago

I would love for other @icpi-div/guidance-capacity-building to weigh in, but here is my two cents...

  1. my preference is to throw periods in the data and underscores elsewhere. When using underscores, it just adds a lot of padding and takes up more space. It should also be added in the guidance that standard date format ordering is YYYYMMDD.

    • 2017_12_15_DontTreadOnMe
    • 2017.12.15_DontTreadOnMe (my preferred option)

  2. I would suggest where countries are used, we should use ISO Codes rather than the country name

    • 2017.12.15_DontTreadOnMe_UnitedStates
    • 2017.12.15_DontTreadOnMe_USA (my preferred option)

  3. in terms of versioning, I would offer that it gets terribly messy quickly when you start adding on reviewers. My recommendation would be just add the last reviewer with the version number also included. In terms of ordering, I put version first and then initials as the versioning is tied to the person, not file. Minor version changes can also be denoted by v2.1 or v2_1. I also tend to write my initials in lower case; personal perference, but think it helps with readibility & tying into the versioning.

    • 2017.12.15_DontTreadOnMe_USA_im_ahc_v3
    • 2017.12.15_DontTreadOnMe_USA_v3_ahc (my preferred option)
shapaklyak commented 6 years ago

Thanks for uploading, @imujawar ! I would suggest to keep this to one page. Noticed a typo, I think it should be or instead of of 5) Do not use quotes of any kind, single of double.

Also, agree w/ @achafetz on his points 1, 2, and 3 above.

Including a standard format to start with for Tools, QC guides, and other types of documents would also help. It seems we're missing the Fiscal Year & Quarter in the naming conventions doc. See below for suggested starting format & example:

jb3436 commented 6 years ago

Thanks all! In discussions with some of the OCM team members, we suggest putting the date at the end to make it easier to sort for the title in SharePoint and windows explorer. I agree with all of your points @achafetz , @imujawar , and @shapaklyak

Examples using your examples

imujawar commented 6 years ago

Thanks a ton for the excellent feedback. Agree with most of the feedback, except for using period . instead of _ underscore for padding dates. Periods can wreak havoc :) when dealing with file extensions and other code-based issues.

jb3436 commented 6 years ago

What do you all think about omitting the padding altogether?

kschlenker commented 6 years ago

I agree that we should not use padding for dates. I don't know about others, but I now frequently run into issues within sharepoint where my file path is too long. I'd advocate minimizing padding except where eliminating it really interferes with readability. To the extent possible I like to use capitals & lowercase lettering to eliminate spaces and underscore padding.

But if you're trying to make it easily sortable within sharepoint then any user/reviewer initials should come after the date

@achafetz, I'm not sure that I agree with the suggestion to use the ISO country codes. While I know that's an international standard, I'm not sure that most people are actually all that familiar with them. We need to make sure that the standards we're using are easily recognizable and not something that users have to google.

Speaking for myself, there are lots of ISO codes that I'd have to look up - for example: India = IND while Indonesia = IDN. Democratic Republic of Congo = COD (not DRC). And I don't actually understand the RAS (Central Asia Region) or RCBs that are listed (both Caribbean & Central America Regions are RCB - but that may have been a typo?).

imujawar commented 6 years ago

These are all good arguments for getting rid of padding within dates. However, I'm afraid we will have to agree to disagree :). I still think padding dates with <_> is important. Removing them would take away emphasis from the date (crucial for version control), especially if we are relegating the date to the end of the file name. Also, continuous dates can sometimes lead to confusion.

shapaklyak commented 6 years ago

Hi all, can we finalize a draft today? Below is a summarized example based on the above discussions. I've also listed the tentative timeline the OCM would like to move forward with.

Italics = information to be included as as applicable Bold = required version control = add version name at the end of the date with initials

Format: TitleOfDocument__DocType_OU__FYXXQX_YYYY.MM.DD._Versioninitials

Timeline

shapaklyak commented 6 years ago

Hi! I've tried to capture information in the attached doc from our meeting yesterday. please add/edit as needed based on our discussion. thx! ICPIFileNamingConventions_20170124_v1.docx

shapaklyak commented 6 years ago

@achafetz @kschlenker @icpi-div/guidance-capacity-building , are we ready to share this with the larger DIV group today at the 1pm meeting?

shapaklyak commented 6 years ago

Hi friends, see the updated version with examples. @icpi-div/icpi-general @icpi-div/guidance-capacity-building @icpi-div/business-intelligence-system-coordination ICPIFileNamingConventions_20170130.docx

shapaklyak commented 6 years ago

@ICPI/guidance-capacity-building thanks everyone!! naming conventions approved by OCM.

next steps:

bowdenj commented 6 years ago

@shapaklyak - Can you confirm name convention? The one in your ticket above seems to be the version that was agreed upon, but the version that went out in the inbrief today looked different (date at beginning compared with date at end). Can you confirm which of the below versions should be used?

Version 1: From this ticket naming conventions

Version 2: From Inbrief inbrief names

I believe the correct version is (1), but please let me know if that is not the case. If it is, we'll update the slide for the inbrief.

shapaklyak commented 6 years ago

@bowdenj @hessionra the naming slide in the inbrief is ancient and incorrect. I think I had asked for it to be removed actually.

bowdenj commented 6 years ago

Thanks @shapaklyak - that makes way more sense. Per our Slack conversation, updated the slide to show a screen shot of the Word document in the hopes that it will stand out more on the Inbrief. Sent slide to @hessionra Inbrief Cluster 02202018_Naming Conventions.pptx