git-branch-db design rationale

[paneq]

File system

tracking/[email protected]/
tracking/[email protected]/2013/
tracking/[email protected]/2013/01/
tracking/[email protected]/2013/01/22/timestamp1.json
tracking/[email protected]/2013/01/22/timestamp2.json

• Every new tracking record is a new file
  • That way by editing this file directly and changing one can fix some issues like invalid time or something like that
• Every person has its own branch based on email: [email protected]
• Person record is also kept in email based directory
• If anyone wants to see records from all projects participants then simple merge between branches will allow to have all the files in working directory without any conflicts.

File content

Tracking stores data in JSON so that they can be easily parsed by third-party services. YAML would not be ok in that case.

[jdudek]

+1

Not sure about tracking subdirectory, but this is just a small detail...

[jdudek]

I'm still thinking about multiple projects. I think I want to have repository for each client that I have and push my entries to calculate total amounts. But I don't want to do any merges. Maybe we should have a subdirectory with project name.

We don't have to resolve this problem now, this should be easy to fix later.

[paneq]

I want to have a repository for every project that I work on, even if it means multiple repositories for multiple projects of the same client. Also I think it would be pretty cool to be able to push entries to the same repo that keeps the code.

Merge is not going to be necessary for a person working on multiple projects. But rather for a client who would like to have files from multiple developers in the repository. In such case merge is required. I am not sure if I speak clearly about this topic. Am I ?

[paneq]

Now i get your point... maybe a subdirectory with a project name is a good idea indeed.

[jdudek]

Also I think it would be pretty cool to be able to push entries to the same repo that keeps the code.

This should be fairly easy. Pushing muon branch to correct ref in git repo should be enough. BTW maybe it would make sense to call default muon branch differently than master, to make this scenario easier.

Merge is not going to be necessary for a person working on multiple projects. But rather for a client who would like to have files from multiple developers in the repository

The client has to make those merges on different branch than entries pushed from developers (otherwise developers will have to pull merge commits before pushing new entries). If we supported statistics across branches, the client would not have to create any commits. I think a stats GUI could have a list of branches and you'd just select them with checkboxes.

[paneq]

New rationale after our discussion

File system

tracking/2013/01/22/timestamp-randomhex.json

• Initially we wanted to keep also emal and project name in directory structure.
  • But we decided not to. There is no reason to have such 2 "special" attributes being part of filename instead of value in tracking file. Because who are we to decide that someone needs actually those 2 attributes ? But nobody does? Maybe some people need 3 of them, like person, project, and client ? So... let's not do it.
• Randomhex to avoid conflicts when entries added manually via muon commit (leading to zeros in seconds and miliseconds)
  • Thanks @jdudek for pointing out such possiblity
• Every new tracking record is a new file
  • That way by editing this file directly and changing one can fix some issues like invalid time or something like that
• Every person has its own branch based on email and project: [email protected]. For simplicity in pushing to one company repo multiple projects by multiple people.
• Checkout different / selected by user branches to be able to compute stats for multiple people and/or projects.

File content

• MUST have start and stop attributes or duration. CAN have 3 of them. Use duration when possible, otherwise compute it dynamically based on start and stop. In case of having 3 of them user may delete duration so that there is no need to compute duration manually when fixing record.
• MAY have email and project. muon will probably put them but our spec says they are not necessary.

[paneq]

• branch name is just a convention. Branches can be named whatever they want :)

[jdudek]

There is a redundancy when keeping date in filenames. I think we should clarify where does this date come form (date of entry creation, start date or stop date) and what to do if it's inconsistent with file contents.

I'd say year-month-day in filename must be equal to start date. I'd prefer to relax this constraint for time because it may be convenient to fix time of an entry manually, without having to rename a file.

There is also this case of entries spanning more than one day. I think we should definitely handle properly entries started before midnight and ended on next day. Not sure about entries ended two days later than started…