Bug#481129: Bug#671503: general: APT repository format is not documented
Michal Suchanek <michal.suchanek@ruk.cuni.cz> writes:
> Excerpts from Ian Jackson's message of Thu May 17 14:53:30 +0200 2012:
>> Michal Suchanek writes ("Re: Bug#671503: general: APT repository format is not documented"):
>> > Excerpts from Filipus Klutiero's message of Wed May 16 18:44:21 +0200 2012:
>> > > Could you clarify how this differs from #481129?
>> >
>> > It's 4 years later.
>> >
>> > Sorry, forgot that I filed the bug already. It's quite some time.
>> >
>> > Given there is no feedback in 4 years I guess it is futile reporting
>> > this.
>>
>> Well, it's useful to bring it up again.
>>
>> > Admittedly there is no text in social contract about using
>> > Debian-proprietary formats. And a format only defined by "apt can read
>> > that" is definitely Debian-proprietary there is no better term for that.
>>
>> Everyone agrees that it would be better if this were documented.
>> (I have struggled on occasion myself due to the lack of
>> documentation.)
>>
>> But I think the use of the word "proprietary" is going too far. It's
>> certainly a special Debian format, but that wouldn't be changed if it
>> were documented. But it's not secret and we publish at least two
>> writer implementations and one reader implementation AFAIK, with
>> proper Free licences.
>
> However, it's easier to reverse-engineer an existing repository than
> the source code so for all practical purposes it's the same as if it
> were closed source.
>
>>
>> > I'd say it's slightly discriminatory against software not part of Debian
>> > that cannot rely on getting notified when "apt can read that" silently
>> > changes, there is no document defining what apt should be able to read
>> > that software authors can rely on to interoperate with apt, one of the
>> > core Debian tools. Apt in turn relies on open standards like HTTP and
>> > FTP to interoperate with the rest of the world.
>>
>> I think this is not an appropriate use of the social contract or its
>> concepts.
>>
>> Rather than complaining that this documentation doesn't exist, how
>> about writing the document yourself ? It's not a trivial job but it
>> should be feasible by looking at the apt source code.
>
> For me it is not feasible at all.
>
> I can, of course, describe what current repositories look like or what
> the current apt code accepts.
>
> However, that has silently changed in the past and is considered apt
> feature, not a bug.
>
>>
>> Once such a document exists, even if it's a bit sketchy or perhaps not
>> entirely accurate, it will be much easier to insist that future
>> changes are likewise documented.
>
> I am not so sure about that.
>
> So long as the document merely describes what apt happens to do at the
> moment rather than apt implementing what the document says there is no
> saying this document has any value.
>
> The status was 'documented' by existing repositories which stopped
> working.
>
> Thanks
>
> Michal
I would suggest you look at existing repositories, whatever scraps of
information is in the manuals and maybe a bit at the source and start to
write a documentation. Once you have that offer it for review and other
people can pitch in their bits of knowledge. Getting the current format
documented right shouldn't be that hard if someone just starts.
And once such a document exists it is much easier to get people do
document changes or hit them over the head if they don't.
Remember that you don't have to be 100% right in what you write. You
only need to write a draft to start the process. Getting people to
comment and correct any mistakes you simply don't know about is much
much easier than getting someone else to write the whole thing.
MfG
Goswin
Reply to: