How to describe your patch

[Alexander Solovyov]

On 2009-02-04, Matt Mackall wrote:

> I'm afraid you've left out absolutely everything that _I_ want to see in
> a major feature description.

Oh, sorry, you are right. I just think about it quite often and so
implied that everyone is doing the same. ;-) And sorry for such long
delay - I was absent.

> I need to know:

> - why we need this feature (in this case, I already know)
> - how you've implemented it
> - what file formats and data structures you've used

Basically there is two types of files. One is a list of a subrepos with
format:

path/to/subrepo path/to/subrepo/source

And others are files, storing current subrepo revision in format
"{hex}\n". They are placed directly in "path/to/subrepo" in store and
are not exposed to the working directory.

> - what choices you've made
> - why the choices you've made are the right ones
> - why the choices you didn't make are the wrong ones

Main choice is how to store revision of subrepo. I've started with
storing it in the .hgsubrepos, but realized (with the help of Brendan
;-) that this would be pain to merge.

Then I've switched to storing revs like described in
NestedRepositories[1], but with slightly other layout: .hgsub/ with
files, storing revision. But I have realized that while it is easy to
merge and look inside, it clutters working dir with a junk and requires
a lot of various checks inside a code.

So eventually I've switched to scheme, based on your suggestion:
revision of subrepository is stored as a text file under the path of
subrepository inside a store: .hg/store/data/path/to/subrepo.i. It is
not revealed to a working copy.

This approach has some advantages: there is no junk in the working dir
and amount of checks is significantly smaller, for example diff command
worked out of box when proper reading/writing of revisions were
implemented. It has one disadvantage: it's harder to merge files which
do not exist in the working copy.

I decided to solve this problem later and currently merge leaves out
revision which you had in working copy.


Another thing is how to mark strings that belong to subrepos: this is
important especially when you have nested subrepos in the subrepos. I
have added ability to prepend strings to ui.ui object, so now messages
looks like:

piranha at gtv ~/test>hg up -C
subrepo: 0 files updated, 0 files merged, 2 files removed, 0 files unresolved
0 files updated, 0 files merged, 0 files removed, 0 files unresolved

I'm not sure that this is best way, but I hadn't thought about anything
better.


And there are two places I'm not sure about: changes in dirstate.py and
in merge.py. They are working, but I'm not sure that I choose right way.

> - what shortcomings exist
> - what compatibility issues exist
> - what's missing, if anything

I think that there are no compatibility issues except that
subrepositories will look like plain text files with hash inside in old
hg. I don't think that this is an issue.

And as I previously mentioned, merge is quite dumb currently. I'm
slightly unsure if it should be upgraded and if it should, then: how?

Finally, there is one not implemented yet feature I'd like to see:
support for other VCSes. But anyway it should be delayed until this code
will be considered as working. ;-)

P.S. I'll read other mails and then send slightly updated version of the
patch.

[1]: http://www.selenic.com/mercurial/wiki/index.cgi/NestedRepositories

-- 
Alexander