You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@whimsical.apache.org by sebb <se...@gmail.com> on 2020/06/25 15:29:03 UTC
COI file layout issue
AFAICT whilst the forms must be signed annually, that does not mean
that the form must be signed at the start of each calendar year.
The current COI file layout assumes a directory for each calendar year.
I think that is going to cause complications.
I think the directory structure should be flattened.
When an officer signs a new form, it should replace the old one (if any).
The signing date could be recorded in a separate index file.
Or maybe the entry in the index file would be sufficient to record agreement?
Re: COI file layout issue
Posted by sebb <se...@gmail.com>.
On Sat, 27 Jun 2020 at 01:15, Craig Russell <ap...@gmail.com> wrote:
>
>
>
> > On Jun 26, 2020, at 3:27 PM, sebb <se...@gmail.com> wrote:
> >
> > On Fri, 26 Jun 2020 at 18:17, Craig Russell <apache.clr@gmail.com <ma...@gmail.com>> wrote:
> >>
> >>
> >>
> >>> On Jun 26, 2020, at 3:00 AM, sebb <se...@gmail.com> wrote:
> >>>
> >>> On Fri, 26 Jun 2020 at 01:56, Craig Russell <ap...@gmail.com> wrote:
> >>>>
> >>>>
> >>>>
> >>>>> On Jun 25, 2020, at 3:23 PM, sebb <se...@gmail.com> wrote:
> >>>>>
> >>>>> On Thu, 25 Jun 2020 at 19:45, Craig Russell <apache.clr@gmail.com <ma...@gmail.com>> wrote:
> >>>>>>
> >>>>>> Hi Sebb,
> >>>>>>
> >>>>>> Thanks very much for your review and comments.
> >>>>>>
> >>>>>>> On Jun 25, 2020, at 8:29 AM, sebb <se...@gmail.com> wrote:
> >>>>>>>
> >>>>>>> AFAICT whilst the forms must be signed annually, that does not mean
> >>>>>>> that the form must be signed at the start of each calendar year.
> >>>>>>
> >>>>>> Right. The only requirement is "annual" signing.
> >>>>>>>
> >>>>>>> The current COI file layout assumes a directory for each calendar year.
> >>>>>>> I think that is going to cause complications.
> >>>>>>
> >>>>>> I don't think it will be a problem. Previous thinking on my part was to have a "current year" link but that ended up being complicated.
> >>>>>>>
> >>>>>>> I think the directory structure should be flattened.
> >>>>>>> When an officer signs a new form, it should replace the old one (if any).
> >>>>>>> The signing date could be recorded in a separate index file.
> >>>>>>
> >>>>>> This is really complicating things unnecessarily. With the current structure, if you have signed three times, there will be three files. If you sign in 2024, that document will be in the 2024 directory. For example,
> >>>>>>
> >>>>>> cd documents/conflict-of-interest/2026; ls
> >>>>>>
> >>>>>> Gives you a list of everyone who signed in 2026. And anyone with credentials can browse to https://svn.apache.org/repos/private/documents/conflict-of-interest/ and see the entire history.
> >>>>>
> >>>>> As it stands, the COI form will only show people who have signed in
> >>>>> the *current* calendar year.
> >>>>> At the beginning of the year that is likely to be no-one, even if they
> >>>>> signed as recently as a month or two ago.
> >>>>
> >>>> Why is that a problem? Folks are required to sign "annually".
> >>>>>
> >>>>>>>
> >>>>>>> Or maybe the entry in the index file would be sufficient to record agreement?
> >>>>>>
> >>>>>> The reason I chose the current structure is so it's easy to tell if an officer has signed "this year". When an officer is first elected/appointed, they sign. Next year, they sign again. If they no longer have a position that requires it, they don't sign until "next time".
> >>>>>>
> >>>>>> The board may change the policy from time to time, and if they change it, the next time anyone signs it, they get the new policy.
> >>>>>>
> >>>>>> "All that is needed" is to create the directory 2021 and copy the template.txt from 2020 to 2021 and we're ready for next year.
> >>>>>>
> >>>>>
> >>>>> Seems to me the template could be in the parent (or sole) directory.
> >>>>> If the template changes, update the single copy.
> >>>>
> >>>> That would be possible. We can also include a header like
> >>>> Apache Conflict of Interest Policy
> >>>> (March 2020)
> >>>>>
> >>>>> However, I think the simplest would be to maintain a single index file
> >>>>> with the signing details.
> >>>>> Is there really any need to store a copy of the processed template file?
> >>>>
> >>>> It is a record of what the officer signed and when. We are requiring officers to sign annually so I think it's important that we keep records of when these documents are signed.
> >>>
> >>> Agreed, so the index file should contain sufficient details to capture
> >>> that agreement.
> >>
> >> My preference is to *not* keep duplicate information but rather to calculate status as needed. Which translates to: no index file as long as the information is available elsewhere.
> >
> > My original thought was to have an index file to make it easier to
> > determine exactly when someone signed, without needing to look at the
> > SVN history or properties of the file.
>
> My approach to this task is to treat the signing of the affirmation document to be "a big deal". Which to me means treat it like a legal document similar to how we treat ICLA, CCLA, and grant documents. A person's affirmation has consequences and is a very serious matter. That's why I firmly believe that a permanent record of the signing along with a paper (email) trail is important.
Is an email *to* the person sufficient?
> What is less important to me is exactly how to interpret "annually" except its plain language meaning of "every year". So once all the required signers have signed, we're done until another team comes along, which happens rarely except immediately after board elections. So this tool will lie dormant for a year, after which it will be front and center for a week.
>
> So while I have no objection to keeping an index file, the real purpose of the tool is served by keeping a permanent record of the affirmations, in a form that is immediately accessible without looking at any other record. So the signatory's name, timestamp, and the actual document which is being affirmed are critically important to be preserved.
Apart from the actual document, the index file would contain those.
The document could be represented by a suitable hash of the contents
(or perhaps the SVN coords).
> >
> > But it then occurred to me that maybe there is no need for the file to
> > be stored in SVN at all.
>
> So we disagree about this. The file that documents the exact thing that is being affirmed is the most important thing to preserve.
Agreed, so I suggested using a hash.
Or indeed the SVN coordinates should be sufficient.
> >
> >> I think of this tool as informative but not prescriptive. Maybe we can look at the wording and come up with some less-prescriptive words.
> >
> > Not sure how that relates to this.
>
> The term "annually" can be read in a few ways, which can be reflected in different wordings on the web page. I suppose you could read it as "it's ok as long as you sign the document sometime this year and sometime next year if you are still an officer next year." But the way the wording is now, we expect all officers to sign "soon". Once the tool is accepted as being useful, useable, and relevant. I'd really like for everyone to take this seriously and sign by the next board meeting. If not, I'll take an action item to reinforce the board's to-be-determined request for all required signers to sign "soon". And not wait until "sometime this year".
>
> Craig
>
> >
> >>>
> >>>>> However it could be emailed to the officer.
> >>>>> If there was a need to validate which version of the template was
> >>>>> agreed, that could be done by saving a hash of the file in the index.
> >>>>
> >>>> I think it's really simple as it is designed now. Everything is in the open, available for audit/review. Only one thing to do once a year: add the <year> directory and template file. Change the template file only if the board updates it.
> >>>>
> >>>> Only problem I see is that it doesn't work due to some permissions problems.
> >>
> >> Which are discussed else-thread. But I thank you here for fixing it.
> >>>
> >>> I agree it's simple to create the documents.
> >>> It's not so simple to check if a person has signed in the last year.
> >>
> >> I'd like to solve this year's problem this year and defer solving next year's problem.
> >>
> >> As I see it, there will be 27 people who shortly sign the affirmation. Secretary will then report that all required signers have signed. (if there are some who have not signed by the end of summer, Secretary might contact them and if they are unresponsive, report to the board; or not.)
> >>
> >> When the calendar rolls over, allofasudden the tool will report many people who are required to sign but have not. Which we will all ignore until a new board comes in. And then we can look at the tool again and decide what to do.
> >
> > Or we could decide now that it's only necessary to record affirmations
> > in a single file and be done with it.
> >
> >> Craig
> >>
> >>>
> >>>> Craig
> >>>>>
> >>>>>> Craig
> >>>>>>
> >>>>>> Craig L Russell
> >>>>>> clr@apache.org <ma...@apache.org> <mailto:clr@apache.org <ma...@apache.org>>
> >>>> Craig L Russell
> >>>> clr@apache.org <ma...@apache.org>
> >>>>
> >>
> >> Craig L Russell
> >> clr@apache.org <ma...@apache.org>
> Craig L Russell
> clr@apache.org
>
Re: COI file layout issue
Posted by Craig Russell <ap...@gmail.com>.
> On Jun 27, 2020, at 3:11 PM, Greg Stein <gs...@apache.org> wrote:
>
> On 2020/06/27 00:15:39, Craig Russell <ap...@gmail.com> wrote:
>> ...
>> So while I have no objection to keeping an index file, the real purpose of the tool is served by keeping a permanent record of the affirmations, in a form that is immediately accessible without looking at any other record. So the signatory's name, timestamp, and the actual document which is being affirmed are critically important to be preserved.
>
> An index file duplicates information that is contained in svn. And svn is authoritative here, since (me) could just go and edit files directly. Whimsy is just a simple tool to figure out who needs to sign (but could/should allow others to do so, too), and give them a way to do the signing.
Yes, and in fact the way it is organized now, an officer could manually print, sign, scan, and commit the clr.pdf to the 2020 directory and the rest of the tooling would work fine. If we really need to, we could document this process but I suspect there will be zero interest in doing it this way, except to prove that it works.
>
>> ...
>> The term "annually" can be read in a few ways, which can be reflected in different wordings on the web
>
> Just read "current year" and "prior year", and weave them together.
Nope. In June 2021 after we have a new team in place, currentyearprioryear would show everyone has signed. Not good enough.
But assuming that we make a trivial change to the tool to iterate the years directories, we can have the sidebar give quick access to all COI documents ever signed, or just the last three or whatever we like. Later.
> You'll be able to synthesize "annual" in any fashion you like. Whether that is calendar, Board election cycle, or fiscal year. "svn info" gives you the last modification date, which is presumably the signing date.
I still prefer to keep it simple. Organize all documents signed in a calendar year in a directory named after that calendar year. Everything else, including the following, is icing.
>
> Presumed signing date. One suggestion: add a property, say "whimsy:signed" and insert the date. That could be modified later, manually, so just highlight any COI file (in the UI) that has more than one revision. A person could still manually construct a file with that property, too. The only *real* test is to ensure the file matches the COI policy that was in effect at the purported time of signing, and that the initial revision of the file's author (the svn:author property) matches the filename.
>
> Note that comparing the file means stripping the metadata from the end. I would suggest to make the file the policy-at-time, and use svn properties for the metadata (that is why they are there).
>
> I'd suggest creating a "validation" function that is simple today, but could be extended to more complex forms, such as suggested above.
Let's get past this year's exercise and wait until something more complicated becomes necessary and agreed.
Craig
>
> Cheers,
> -g
>
Craig L Russell
clr@apache.org
Re: COI file layout issue
Posted by Greg Stein <gs...@apache.org>.
On 2020/06/27 00:15:39, Craig Russell <ap...@gmail.com> wrote:
>...
> So while I have no objection to keeping an index file, the real purpose of the tool is served by keeping a permanent record of the affirmations, in a form that is immediately accessible without looking at any other record. So the signatory's name, timestamp, and the actual document which is being affirmed are critically important to be preserved.
An index file duplicates information that is contained in svn. And svn is authoritative here, since (me) could just go and edit files directly. Whimsy is just a simple tool to figure out who needs to sign (but could/should allow others to do so, too), and give them a way to do the signing.
>...
> The term "annually" can be read in a few ways, which can be reflected in different wordings on the web
Just read "current year" and "prior year", and weave them together. You'll be able to synthesize "annual" in any fashion you like. Whether that is calendar, Board election cycle, or fiscal year. "svn info" gives you the last modification date, which is presumably the signing date.
Presumed signing date. One suggestion: add a property, say "whimsy:signed" and insert the date. That could be modified later, manually, so just highlight any COI file (in the UI) that has more than one revision. A person could still manually construct a file with that property, too. The only *real* test is to ensure the file matches the COI policy that was in effect at the purported time of signing, and that the initial revision of the file's author (the svn:author property) matches the filename.
Note that comparing the file means stripping the metadata from the end. I would suggest to make the file the policy-at-time, and use svn properties for the metadata (that is why they are there).
I'd suggest creating a "validation" function that is simple today, but could be extended to more complex forms, such as suggested above.
Cheers,
-g
Re: COI file layout issue
Posted by Craig Russell <ap...@gmail.com>.
> On Jun 26, 2020, at 3:27 PM, sebb <se...@gmail.com> wrote:
>
> On Fri, 26 Jun 2020 at 18:17, Craig Russell <apache.clr@gmail.com <ma...@gmail.com>> wrote:
>>
>>
>>
>>> On Jun 26, 2020, at 3:00 AM, sebb <se...@gmail.com> wrote:
>>>
>>> On Fri, 26 Jun 2020 at 01:56, Craig Russell <ap...@gmail.com> wrote:
>>>>
>>>>
>>>>
>>>>> On Jun 25, 2020, at 3:23 PM, sebb <se...@gmail.com> wrote:
>>>>>
>>>>> On Thu, 25 Jun 2020 at 19:45, Craig Russell <apache.clr@gmail.com <ma...@gmail.com>> wrote:
>>>>>>
>>>>>> Hi Sebb,
>>>>>>
>>>>>> Thanks very much for your review and comments.
>>>>>>
>>>>>>> On Jun 25, 2020, at 8:29 AM, sebb <se...@gmail.com> wrote:
>>>>>>>
>>>>>>> AFAICT whilst the forms must be signed annually, that does not mean
>>>>>>> that the form must be signed at the start of each calendar year.
>>>>>>
>>>>>> Right. The only requirement is "annual" signing.
>>>>>>>
>>>>>>> The current COI file layout assumes a directory for each calendar year.
>>>>>>> I think that is going to cause complications.
>>>>>>
>>>>>> I don't think it will be a problem. Previous thinking on my part was to have a "current year" link but that ended up being complicated.
>>>>>>>
>>>>>>> I think the directory structure should be flattened.
>>>>>>> When an officer signs a new form, it should replace the old one (if any).
>>>>>>> The signing date could be recorded in a separate index file.
>>>>>>
>>>>>> This is really complicating things unnecessarily. With the current structure, if you have signed three times, there will be three files. If you sign in 2024, that document will be in the 2024 directory. For example,
>>>>>>
>>>>>> cd documents/conflict-of-interest/2026; ls
>>>>>>
>>>>>> Gives you a list of everyone who signed in 2026. And anyone with credentials can browse to https://svn.apache.org/repos/private/documents/conflict-of-interest/ and see the entire history.
>>>>>
>>>>> As it stands, the COI form will only show people who have signed in
>>>>> the *current* calendar year.
>>>>> At the beginning of the year that is likely to be no-one, even if they
>>>>> signed as recently as a month or two ago.
>>>>
>>>> Why is that a problem? Folks are required to sign "annually".
>>>>>
>>>>>>>
>>>>>>> Or maybe the entry in the index file would be sufficient to record agreement?
>>>>>>
>>>>>> The reason I chose the current structure is so it's easy to tell if an officer has signed "this year". When an officer is first elected/appointed, they sign. Next year, they sign again. If they no longer have a position that requires it, they don't sign until "next time".
>>>>>>
>>>>>> The board may change the policy from time to time, and if they change it, the next time anyone signs it, they get the new policy.
>>>>>>
>>>>>> "All that is needed" is to create the directory 2021 and copy the template.txt from 2020 to 2021 and we're ready for next year.
>>>>>>
>>>>>
>>>>> Seems to me the template could be in the parent (or sole) directory.
>>>>> If the template changes, update the single copy.
>>>>
>>>> That would be possible. We can also include a header like
>>>> Apache Conflict of Interest Policy
>>>> (March 2020)
>>>>>
>>>>> However, I think the simplest would be to maintain a single index file
>>>>> with the signing details.
>>>>> Is there really any need to store a copy of the processed template file?
>>>>
>>>> It is a record of what the officer signed and when. We are requiring officers to sign annually so I think it's important that we keep records of when these documents are signed.
>>>
>>> Agreed, so the index file should contain sufficient details to capture
>>> that agreement.
>>
>> My preference is to *not* keep duplicate information but rather to calculate status as needed. Which translates to: no index file as long as the information is available elsewhere.
>
> My original thought was to have an index file to make it easier to
> determine exactly when someone signed, without needing to look at the
> SVN history or properties of the file.
My approach to this task is to treat the signing of the affirmation document to be "a big deal". Which to me means treat it like a legal document similar to how we treat ICLA, CCLA, and grant documents. A person's affirmation has consequences and is a very serious matter. That's why I firmly believe that a permanent record of the signing along with a paper (email) trail is important.
What is less important to me is exactly how to interpret "annually" except its plain language meaning of "every year". So once all the required signers have signed, we're done until another team comes along, which happens rarely except immediately after board elections. So this tool will lie dormant for a year, after which it will be front and center for a week.
So while I have no objection to keeping an index file, the real purpose of the tool is served by keeping a permanent record of the affirmations, in a form that is immediately accessible without looking at any other record. So the signatory's name, timestamp, and the actual document which is being affirmed are critically important to be preserved.
>
> But it then occurred to me that maybe there is no need for the file to
> be stored in SVN at all.
So we disagree about this. The file that documents the exact thing that is being affirmed is the most important thing to preserve.
>
>> I think of this tool as informative but not prescriptive. Maybe we can look at the wording and come up with some less-prescriptive words.
>
> Not sure how that relates to this.
The term "annually" can be read in a few ways, which can be reflected in different wordings on the web page. I suppose you could read it as "it's ok as long as you sign the document sometime this year and sometime next year if you are still an officer next year." But the way the wording is now, we expect all officers to sign "soon". Once the tool is accepted as being useful, useable, and relevant. I'd really like for everyone to take this seriously and sign by the next board meeting. If not, I'll take an action item to reinforce the board's to-be-determined request for all required signers to sign "soon". And not wait until "sometime this year".
Craig
>
>>>
>>>>> However it could be emailed to the officer.
>>>>> If there was a need to validate which version of the template was
>>>>> agreed, that could be done by saving a hash of the file in the index.
>>>>
>>>> I think it's really simple as it is designed now. Everything is in the open, available for audit/review. Only one thing to do once a year: add the <year> directory and template file. Change the template file only if the board updates it.
>>>>
>>>> Only problem I see is that it doesn't work due to some permissions problems.
>>
>> Which are discussed else-thread. But I thank you here for fixing it.
>>>
>>> I agree it's simple to create the documents.
>>> It's not so simple to check if a person has signed in the last year.
>>
>> I'd like to solve this year's problem this year and defer solving next year's problem.
>>
>> As I see it, there will be 27 people who shortly sign the affirmation. Secretary will then report that all required signers have signed. (if there are some who have not signed by the end of summer, Secretary might contact them and if they are unresponsive, report to the board; or not.)
>>
>> When the calendar rolls over, allofasudden the tool will report many people who are required to sign but have not. Which we will all ignore until a new board comes in. And then we can look at the tool again and decide what to do.
>
> Or we could decide now that it's only necessary to record affirmations
> in a single file and be done with it.
>
>> Craig
>>
>>>
>>>> Craig
>>>>>
>>>>>> Craig
>>>>>>
>>>>>> Craig L Russell
>>>>>> clr@apache.org <ma...@apache.org> <mailto:clr@apache.org <ma...@apache.org>>
>>>> Craig L Russell
>>>> clr@apache.org <ma...@apache.org>
>>>>
>>
>> Craig L Russell
>> clr@apache.org <ma...@apache.org>
Craig L Russell
clr@apache.org
Re: COI file layout issue
Posted by sebb <se...@gmail.com>.
On Fri, 26 Jun 2020 at 18:17, Craig Russell <ap...@gmail.com> wrote:
>
>
>
> > On Jun 26, 2020, at 3:00 AM, sebb <se...@gmail.com> wrote:
> >
> > On Fri, 26 Jun 2020 at 01:56, Craig Russell <ap...@gmail.com> wrote:
> >>
> >>
> >>
> >>> On Jun 25, 2020, at 3:23 PM, sebb <se...@gmail.com> wrote:
> >>>
> >>> On Thu, 25 Jun 2020 at 19:45, Craig Russell <apache.clr@gmail.com <ma...@gmail.com>> wrote:
> >>>>
> >>>> Hi Sebb,
> >>>>
> >>>> Thanks very much for your review and comments.
> >>>>
> >>>>> On Jun 25, 2020, at 8:29 AM, sebb <se...@gmail.com> wrote:
> >>>>>
> >>>>> AFAICT whilst the forms must be signed annually, that does not mean
> >>>>> that the form must be signed at the start of each calendar year.
> >>>>
> >>>> Right. The only requirement is "annual" signing.
> >>>>>
> >>>>> The current COI file layout assumes a directory for each calendar year.
> >>>>> I think that is going to cause complications.
> >>>>
> >>>> I don't think it will be a problem. Previous thinking on my part was to have a "current year" link but that ended up being complicated.
> >>>>>
> >>>>> I think the directory structure should be flattened.
> >>>>> When an officer signs a new form, it should replace the old one (if any).
> >>>>> The signing date could be recorded in a separate index file.
> >>>>
> >>>> This is really complicating things unnecessarily. With the current structure, if you have signed three times, there will be three files. If you sign in 2024, that document will be in the 2024 directory. For example,
> >>>>
> >>>> cd documents/conflict-of-interest/2026; ls
> >>>>
> >>>> Gives you a list of everyone who signed in 2026. And anyone with credentials can browse to https://svn.apache.org/repos/private/documents/conflict-of-interest/ and see the entire history.
> >>>
> >>> As it stands, the COI form will only show people who have signed in
> >>> the *current* calendar year.
> >>> At the beginning of the year that is likely to be no-one, even if they
> >>> signed as recently as a month or two ago.
> >>
> >> Why is that a problem? Folks are required to sign "annually".
> >>>
> >>>>>
> >>>>> Or maybe the entry in the index file would be sufficient to record agreement?
> >>>>
> >>>> The reason I chose the current structure is so it's easy to tell if an officer has signed "this year". When an officer is first elected/appointed, they sign. Next year, they sign again. If they no longer have a position that requires it, they don't sign until "next time".
> >>>>
> >>>> The board may change the policy from time to time, and if they change it, the next time anyone signs it, they get the new policy.
> >>>>
> >>>> "All that is needed" is to create the directory 2021 and copy the template.txt from 2020 to 2021 and we're ready for next year.
> >>>>
> >>>
> >>> Seems to me the template could be in the parent (or sole) directory.
> >>> If the template changes, update the single copy.
> >>
> >> That would be possible. We can also include a header like
> >> Apache Conflict of Interest Policy
> >> (March 2020)
> >>>
> >>> However, I think the simplest would be to maintain a single index file
> >>> with the signing details.
> >>> Is there really any need to store a copy of the processed template file?
> >>
> >> It is a record of what the officer signed and when. We are requiring officers to sign annually so I think it's important that we keep records of when these documents are signed.
> >
> > Agreed, so the index file should contain sufficient details to capture
> > that agreement.
>
> My preference is to *not* keep duplicate information but rather to calculate status as needed. Which translates to: no index file as long as the information is available elsewhere.
My original thought was to have an index file to make it easier to
determine exactly when someone signed, without needing to look at the
SVN history or properties of the file.
But it then occurred to me that maybe there is no need for the file to
be stored in SVN at all.
> I think of this tool as informative but not prescriptive. Maybe we can look at the wording and come up with some less-prescriptive words.
Not sure how that relates to this.
> >
> >>> However it could be emailed to the officer.
> >>> If there was a need to validate which version of the template was
> >>> agreed, that could be done by saving a hash of the file in the index.
> >>
> >> I think it's really simple as it is designed now. Everything is in the open, available for audit/review. Only one thing to do once a year: add the <year> directory and template file. Change the template file only if the board updates it.
> >>
> >> Only problem I see is that it doesn't work due to some permissions problems.
>
> Which are discussed else-thread. But I thank you here for fixing it.
> >
> > I agree it's simple to create the documents.
> > It's not so simple to check if a person has signed in the last year.
>
> I'd like to solve this year's problem this year and defer solving next year's problem.
>
> As I see it, there will be 27 people who shortly sign the affirmation. Secretary will then report that all required signers have signed. (if there are some who have not signed by the end of summer, Secretary might contact them and if they are unresponsive, report to the board; or not.)
>
> When the calendar rolls over, allofasudden the tool will report many people who are required to sign but have not. Which we will all ignore until a new board comes in. And then we can look at the tool again and decide what to do.
Or we could decide now that it's only necessary to record affirmations
in a single file and be done with it.
> Craig
>
> >
> >> Craig
> >>>
> >>>> Craig
> >>>>
> >>>> Craig L Russell
> >>>> clr@apache.org <ma...@apache.org>
> >> Craig L Russell
> >> clr@apache.org
> >>
>
> Craig L Russell
> clr@apache.org
>
Re: COI file layout issue
Posted by Craig Russell <ap...@gmail.com>.
> On Jun 26, 2020, at 3:00 AM, sebb <se...@gmail.com> wrote:
>
> On Fri, 26 Jun 2020 at 01:56, Craig Russell <ap...@gmail.com> wrote:
>>
>>
>>
>>> On Jun 25, 2020, at 3:23 PM, sebb <se...@gmail.com> wrote:
>>>
>>> On Thu, 25 Jun 2020 at 19:45, Craig Russell <apache.clr@gmail.com <ma...@gmail.com>> wrote:
>>>>
>>>> Hi Sebb,
>>>>
>>>> Thanks very much for your review and comments.
>>>>
>>>>> On Jun 25, 2020, at 8:29 AM, sebb <se...@gmail.com> wrote:
>>>>>
>>>>> AFAICT whilst the forms must be signed annually, that does not mean
>>>>> that the form must be signed at the start of each calendar year.
>>>>
>>>> Right. The only requirement is "annual" signing.
>>>>>
>>>>> The current COI file layout assumes a directory for each calendar year.
>>>>> I think that is going to cause complications.
>>>>
>>>> I don't think it will be a problem. Previous thinking on my part was to have a "current year" link but that ended up being complicated.
>>>>>
>>>>> I think the directory structure should be flattened.
>>>>> When an officer signs a new form, it should replace the old one (if any).
>>>>> The signing date could be recorded in a separate index file.
>>>>
>>>> This is really complicating things unnecessarily. With the current structure, if you have signed three times, there will be three files. If you sign in 2024, that document will be in the 2024 directory. For example,
>>>>
>>>> cd documents/conflict-of-interest/2026; ls
>>>>
>>>> Gives you a list of everyone who signed in 2026. And anyone with credentials can browse to https://svn.apache.org/repos/private/documents/conflict-of-interest/ and see the entire history.
>>>
>>> As it stands, the COI form will only show people who have signed in
>>> the *current* calendar year.
>>> At the beginning of the year that is likely to be no-one, even if they
>>> signed as recently as a month or two ago.
>>
>> Why is that a problem? Folks are required to sign "annually".
>>>
>>>>>
>>>>> Or maybe the entry in the index file would be sufficient to record agreement?
>>>>
>>>> The reason I chose the current structure is so it's easy to tell if an officer has signed "this year". When an officer is first elected/appointed, they sign. Next year, they sign again. If they no longer have a position that requires it, they don't sign until "next time".
>>>>
>>>> The board may change the policy from time to time, and if they change it, the next time anyone signs it, they get the new policy.
>>>>
>>>> "All that is needed" is to create the directory 2021 and copy the template.txt from 2020 to 2021 and we're ready for next year.
>>>>
>>>
>>> Seems to me the template could be in the parent (or sole) directory.
>>> If the template changes, update the single copy.
>>
>> That would be possible. We can also include a header like
>> Apache Conflict of Interest Policy
>> (March 2020)
>>>
>>> However, I think the simplest would be to maintain a single index file
>>> with the signing details.
>>> Is there really any need to store a copy of the processed template file?
>>
>> It is a record of what the officer signed and when. We are requiring officers to sign annually so I think it's important that we keep records of when these documents are signed.
>
> Agreed, so the index file should contain sufficient details to capture
> that agreement.
My preference is to *not* keep duplicate information but rather to calculate status as needed. Which translates to: no index file as long as the information is available elsewhere.
I think of this tool as informative but not prescriptive. Maybe we can look at the wording and come up with some less-prescriptive words.
>
>>> However it could be emailed to the officer.
>>> If there was a need to validate which version of the template was
>>> agreed, that could be done by saving a hash of the file in the index.
>>
>> I think it's really simple as it is designed now. Everything is in the open, available for audit/review. Only one thing to do once a year: add the <year> directory and template file. Change the template file only if the board updates it.
>>
>> Only problem I see is that it doesn't work due to some permissions problems.
Which are discussed else-thread. But I thank you here for fixing it.
>
> I agree it's simple to create the documents.
> It's not so simple to check if a person has signed in the last year.
I'd like to solve this year's problem this year and defer solving next year's problem.
As I see it, there will be 27 people who shortly sign the affirmation. Secretary will then report that all required signers have signed. (if there are some who have not signed by the end of summer, Secretary might contact them and if they are unresponsive, report to the board; or not.)
When the calendar rolls over, allofasudden the tool will report many people who are required to sign but have not. Which we will all ignore until a new board comes in. And then we can look at the tool again and decide what to do.
Craig
>
>> Craig
>>>
>>>> Craig
>>>>
>>>> Craig L Russell
>>>> clr@apache.org <ma...@apache.org>
>> Craig L Russell
>> clr@apache.org
>>
Craig L Russell
clr@apache.org
Re: COI file layout issue
Posted by sebb <se...@gmail.com>.
On Fri, 26 Jun 2020 at 01:56, Craig Russell <ap...@gmail.com> wrote:
>
>
>
> > On Jun 25, 2020, at 3:23 PM, sebb <se...@gmail.com> wrote:
> >
> > On Thu, 25 Jun 2020 at 19:45, Craig Russell <apache.clr@gmail.com <ma...@gmail.com>> wrote:
> >>
> >> Hi Sebb,
> >>
> >> Thanks very much for your review and comments.
> >>
> >>> On Jun 25, 2020, at 8:29 AM, sebb <se...@gmail.com> wrote:
> >>>
> >>> AFAICT whilst the forms must be signed annually, that does not mean
> >>> that the form must be signed at the start of each calendar year.
> >>
> >> Right. The only requirement is "annual" signing.
> >>>
> >>> The current COI file layout assumes a directory for each calendar year.
> >>> I think that is going to cause complications.
> >>
> >> I don't think it will be a problem. Previous thinking on my part was to have a "current year" link but that ended up being complicated.
> >>>
> >>> I think the directory structure should be flattened.
> >>> When an officer signs a new form, it should replace the old one (if any).
> >>> The signing date could be recorded in a separate index file.
> >>
> >> This is really complicating things unnecessarily. With the current structure, if you have signed three times, there will be three files. If you sign in 2024, that document will be in the 2024 directory. For example,
> >>
> >> cd documents/conflict-of-interest/2026; ls
> >>
> >> Gives you a list of everyone who signed in 2026. And anyone with credentials can browse to https://svn.apache.org/repos/private/documents/conflict-of-interest/ and see the entire history.
> >
> > As it stands, the COI form will only show people who have signed in
> > the *current* calendar year.
> > At the beginning of the year that is likely to be no-one, even if they
> > signed as recently as a month or two ago.
>
> Why is that a problem? Folks are required to sign "annually".
> >
> >>>
> >>> Or maybe the entry in the index file would be sufficient to record agreement?
> >>
> >> The reason I chose the current structure is so it's easy to tell if an officer has signed "this year". When an officer is first elected/appointed, they sign. Next year, they sign again. If they no longer have a position that requires it, they don't sign until "next time".
> >>
> >> The board may change the policy from time to time, and if they change it, the next time anyone signs it, they get the new policy.
> >>
> >> "All that is needed" is to create the directory 2021 and copy the template.txt from 2020 to 2021 and we're ready for next year.
> >>
> >
> > Seems to me the template could be in the parent (or sole) directory.
> > If the template changes, update the single copy.
>
> That would be possible. We can also include a header like
> Apache Conflict of Interest Policy
> (March 2020)
> >
> > However, I think the simplest would be to maintain a single index file
> > with the signing details.
> > Is there really any need to store a copy of the processed template file?
>
> It is a record of what the officer signed and when. We are requiring officers to sign annually so I think it's important that we keep records of when these documents are signed.
Agreed, so the index file should contain sufficient details to capture
that agreement.
> > However it could be emailed to the officer.
> > If there was a need to validate which version of the template was
> > agreed, that could be done by saving a hash of the file in the index.
>
> I think it's really simple as it is designed now. Everything is in the open, available for audit/review. Only one thing to do once a year: add the <year> directory and template file. Change the template file only if the board updates it.
>
> Only problem I see is that it doesn't work due to some permissions problems.
I agree it's simple to create the documents.
It's not so simple to check if a person has signed in the last year.
> Craig
> >
> >> Craig
> >>
> >> Craig L Russell
> >> clr@apache.org <ma...@apache.org>
> Craig L Russell
> clr@apache.org
>
Re: COI file layout issue
Posted by Craig Russell <ap...@gmail.com>.
> On Jun 25, 2020, at 3:23 PM, sebb <se...@gmail.com> wrote:
>
> On Thu, 25 Jun 2020 at 19:45, Craig Russell <apache.clr@gmail.com <ma...@gmail.com>> wrote:
>>
>> Hi Sebb,
>>
>> Thanks very much for your review and comments.
>>
>>> On Jun 25, 2020, at 8:29 AM, sebb <se...@gmail.com> wrote:
>>>
>>> AFAICT whilst the forms must be signed annually, that does not mean
>>> that the form must be signed at the start of each calendar year.
>>
>> Right. The only requirement is "annual" signing.
>>>
>>> The current COI file layout assumes a directory for each calendar year.
>>> I think that is going to cause complications.
>>
>> I don't think it will be a problem. Previous thinking on my part was to have a "current year" link but that ended up being complicated.
>>>
>>> I think the directory structure should be flattened.
>>> When an officer signs a new form, it should replace the old one (if any).
>>> The signing date could be recorded in a separate index file.
>>
>> This is really complicating things unnecessarily. With the current structure, if you have signed three times, there will be three files. If you sign in 2024, that document will be in the 2024 directory. For example,
>>
>> cd documents/conflict-of-interest/2026; ls
>>
>> Gives you a list of everyone who signed in 2026. And anyone with credentials can browse to https://svn.apache.org/repos/private/documents/conflict-of-interest/ and see the entire history.
>
> As it stands, the COI form will only show people who have signed in
> the *current* calendar year.
> At the beginning of the year that is likely to be no-one, even if they
> signed as recently as a month or two ago.
Why is that a problem? Folks are required to sign "annually".
>
>>>
>>> Or maybe the entry in the index file would be sufficient to record agreement?
>>
>> The reason I chose the current structure is so it's easy to tell if an officer has signed "this year". When an officer is first elected/appointed, they sign. Next year, they sign again. If they no longer have a position that requires it, they don't sign until "next time".
>>
>> The board may change the policy from time to time, and if they change it, the next time anyone signs it, they get the new policy.
>>
>> "All that is needed" is to create the directory 2021 and copy the template.txt from 2020 to 2021 and we're ready for next year.
>>
>
> Seems to me the template could be in the parent (or sole) directory.
> If the template changes, update the single copy.
That would be possible. We can also include a header like
Apache Conflict of Interest Policy
(March 2020)
>
> However, I think the simplest would be to maintain a single index file
> with the signing details.
> Is there really any need to store a copy of the processed template file?
It is a record of what the officer signed and when. We are requiring officers to sign annually so I think it's important that we keep records of when these documents are signed.
> However it could be emailed to the officer.
> If there was a need to validate which version of the template was
> agreed, that could be done by saving a hash of the file in the index.
I think it's really simple as it is designed now. Everything is in the open, available for audit/review. Only one thing to do once a year: add the <year> directory and template file. Change the template file only if the board updates it.
Only problem I see is that it doesn't work due to some permissions problems.
Craig
>
>> Craig
>>
>> Craig L Russell
>> clr@apache.org <ma...@apache.org>
Craig L Russell
clr@apache.org
Re: COI file layout issue
Posted by sebb <se...@gmail.com>.
On Thu, 25 Jun 2020 at 19:45, Craig Russell <ap...@gmail.com> wrote:
>
> Hi Sebb,
>
> Thanks very much for your review and comments.
>
> > On Jun 25, 2020, at 8:29 AM, sebb <se...@gmail.com> wrote:
> >
> > AFAICT whilst the forms must be signed annually, that does not mean
> > that the form must be signed at the start of each calendar year.
>
> Right. The only requirement is "annual" signing.
> >
> > The current COI file layout assumes a directory for each calendar year.
> > I think that is going to cause complications.
>
> I don't think it will be a problem. Previous thinking on my part was to have a "current year" link but that ended up being complicated.
> >
> > I think the directory structure should be flattened.
> > When an officer signs a new form, it should replace the old one (if any).
> > The signing date could be recorded in a separate index file.
>
> This is really complicating things unnecessarily. With the current structure, if you have signed three times, there will be three files. If you sign in 2024, that document will be in the 2024 directory. For example,
>
> cd documents/conflict-of-interest/2026; ls
>
> Gives you a list of everyone who signed in 2026. And anyone with credentials can browse to https://svn.apache.org/repos/private/documents/conflict-of-interest/ and see the entire history.
As it stands, the COI form will only show people who have signed in
the *current* calendar year.
At the beginning of the year that is likely to be no-one, even if they
signed as recently as a month or two ago.
> >
> > Or maybe the entry in the index file would be sufficient to record agreement?
>
> The reason I chose the current structure is so it's easy to tell if an officer has signed "this year". When an officer is first elected/appointed, they sign. Next year, they sign again. If they no longer have a position that requires it, they don't sign until "next time".
>
> The board may change the policy from time to time, and if they change it, the next time anyone signs it, they get the new policy.
>
> "All that is needed" is to create the directory 2021 and copy the template.txt from 2020 to 2021 and we're ready for next year.
>
Seems to me the template could be in the parent (or sole) directory.
If the template changes, update the single copy.
However, I think the simplest would be to maintain a single index file
with the signing details.
Is there really any need to store a copy of the processed template file?
However it could be emailed to the officer.
If there was a need to validate which version of the template was
agreed, that could be done by saving a hash of the file in the index.
> Craig
>
> Craig L Russell
> clr@apache.org
>
Re: COI file layout issue
Posted by Craig Russell <ap...@gmail.com>.
Hi Sebb,
Thanks very much for your review and comments.
> On Jun 25, 2020, at 8:29 AM, sebb <se...@gmail.com> wrote:
>
> AFAICT whilst the forms must be signed annually, that does not mean
> that the form must be signed at the start of each calendar year.
Right. The only requirement is "annual" signing.
>
> The current COI file layout assumes a directory for each calendar year.
> I think that is going to cause complications.
I don't think it will be a problem. Previous thinking on my part was to have a "current year" link but that ended up being complicated.
>
> I think the directory structure should be flattened.
> When an officer signs a new form, it should replace the old one (if any).
> The signing date could be recorded in a separate index file.
This is really complicating things unnecessarily. With the current structure, if you have signed three times, there will be three files. If you sign in 2024, that document will be in the 2024 directory. For example,
cd documents/conflict-of-interest/2026; ls
Gives you a list of everyone who signed in 2026. And anyone with credentials can browse to https://svn.apache.org/repos/private/documents/conflict-of-interest/ and see the entire history.
>
> Or maybe the entry in the index file would be sufficient to record agreement?
The reason I chose the current structure is so it's easy to tell if an officer has signed "this year". When an officer is first elected/appointed, they sign. Next year, they sign again. If they no longer have a position that requires it, they don't sign until "next time".
The board may change the policy from time to time, and if they change it, the next time anyone signs it, they get the new policy.
"All that is needed" is to create the directory 2021 and copy the template.txt from 2020 to 2021 and we're ready for next year.
Craig
Craig L Russell
clr@apache.org