Re: Guix wiki

[Maxim Cournoyer]

Hi Attila,

Attila Lendvai  writes:

>> 1. People find the [data] service provides value (can someone restate what 
>> that
>> value is exactly? Is it needed e.g. to power
>
>
> if you allow hijacking the above into the wiki discussion:
>
> this is a good example where a wiki page (central, easily editable,
> capturing the current state) would tremendously help this
> discussion. who, where, why, what, etc...

This assumes there would be people willing to write information there
and maintain it up to date, which is far from granted.  Other than that,
I get your point.

-- 
Thanks,
Maxim

Re: Guix wiki

[Attila Lendvai]

> 1. People find the [data] service provides value (can someone restate what 
> that
> value is exactly? Is it needed e.g. to power


if you allow hijacking the above into the wiki discussion:

this is a good example where a wiki page (central, easily editable, capturing 
the current state) would tremendously help this discussion. who, where, why, 
what, etc...

such a wiki doesn't need to be completely open for self-registration, which is 
the source of most issues. kinda like the commit bit, but with more relaxed 
requirements. maybe invite-only, or a somewhat hidden static secret could be 
used for gatekeeping the registration.

it's an illusion that everything is captured by the mailing list archive when 
finding stuff is inefficient in a discussion log. also, the wiki displays the 
current state, not the entire bumpy road getting there.

i know about https://libreplanet.org/wiki/Group:Guix but the search engines 
don't really. and i don't know how others feel about it, but i subconsciously 
don't take it seriously because the search box is not focused on guix, and in 
this form it feels like just an aftertought, not a guix wiki.

-- 
• attila lendvai
• PGP: 963F 5D5F 45C7 DFCD 0A39
--
“If you are ever tempted to look for outside approval, realize that you have 
compromised your integrity. If you need a witness, be your own.”
— Epictetus (c. 55–135 AD)

Re: Guix wiki

[Attila Lendvai]

> Suggestion: clashing names is not a problem, as long as the final
> package to build actually has an unambigious name. Also, it is not
> necessary to actually give these intermediate packages a variable name,
> maybe do something like
>
> (define-module (gnu packages ...))
> (define-public foo [... a conventional guix package definition ...])
>
> (define-module (my-reproducibility-test)
> #:use-module (gnu packages ...))
>
> (define %version-pins ; <-- TODO: teach "guix import go --pin-versions" to 
> produce this kind of structure?
> ;; package name / version / hash
> '(("go-github-com-operatorfoundation-shapeshifter-transports" "0.1.2" 
> "0f1hzhk3q2fgqdg14zlg3z0s0ib1y9xwj89qnjk95b37zbgqjgsb")
> [...]))
>
> (define pin-input
> (match-lambda
> ((label package . rest)
> (cons* label (pin package) rest
>
> (define pin
> (mlambda (package)
> If the package name does not occur in %version-pins --> return package 
> unchanged.
>
> Otherwise, return
> (package
> (inherit package)
> (version the new version)
> (source (origin (inherit (package-source package))
> an appropriately adjusted commit
> the new hash))
> ;; TODO: other versions of dependencies might need extra dependencies
> (inputs (map pin-input package))
> (native-inputs (map pin-input package))
> (propagated-inputs (map pin-input package
>
> (define-public my-reproducibility-test-foo
> (package
> (inherit (pin foo))
> (name "foo-as-found-elsewhere")))
>
> Does that suit your purposes?


i'm afraid i can't answer that without further experiments. an immediate 
concern of mine is that i've seen wild fluctuations in the dependencies of 
different versions of the same go modules.

this is a great idea, though. thanks, noted!

--
• attila lendvai
• PGP: 963F 5D5F 45C7 DFCD 0A39
--
“When, among a hundred men one man dominates ninety-nine, it is iniquity and 
despotism. When ten dominate ninety, it is injustice and oligarchy. When 
fifty-one dominate forty-nine (and this only theoretically, for, in reality, 
among these fifty-one there are ten or twelve masters), then it is justice and 
liberty. Could anyone imagine anything more ridiculous and absurd than this 
reasoning?”
— Leo Tolstoy (1828–1910), 'The Law of Love and the Law of Violence' 
(1908)

Re: Guix wiki

[Aurora]

Vagrant Cascadian  writes:

> On 2022-01-09, Matt wrote:
>> Concern 7: the manual can easily be read and modified while offline
>>
>>   This is another good point. Things shouldn't be tied to the
>>   internet.
>>
>>   Fortunately, most wikis allow users to download the wiki (apart from
>>   tools like wget).
>>
>>   Unfortunately, the manual requires users to have a full system
>>   install and either commit rights or an extended conversion in order
>>   to modify.  To quote the Wikipedia on wikis,
>>
>>   "All that people require to contribute is a computer [including a
>>   mobile device], Internet access, a web browser, and a basic
>>   understanding of a simple markup language (e.g. MediaWiki markup
>>   language)"
>
> There are definitely wikis which use fairly simple markup
> (e.g. markdown) and can usefully be read and updated online via a web
> interface and git offline or online. The one I'm most familiar with is
> ikiwiki (available in guix), though don't have a lot of experience
> updating it via the web interface.
>
>
> live well,
>   vagrant

Personally this is what I'd consider the primary concern before a wiki
can be considered even remotely seriously.

While some wikis allow you to download the database, the vast majority
do not allow you to export or import diffs & modifications (mediawiki's
own support for this feature seems to be underdocumented), so what you
get is a lot less useful than even just a directory hierarchy with a
bunch of markdown files like some projects and forges do for their docs.

Other than ikiwiki and [fossil][1] I don't know of any wiki that
supports these features.

1: https://fossil-scm.org/home/doc/trunk/www/wikitheory.wiki

Re: Guix wiki

[Maxime Devos]

Attila Lendvai schreef op ma 11-04-2022 om 06:49 [+]:
> these names are pretty much independent from each other
> (modulo some conventions), and this is an issue for the importers.
> more specifically the go importer, that currently needs scheme variable
> names to refer to the identified dependencies, while it can only look up
> the package objects. these objects know nothing about the scheme
> variables they are stored in.

Use package-definition-location.  From the file name, it should be
possibly to derive a module name.  The sexp at this location can also
be read -- the sexp includes the surrounding (define-public foo ...),
so the variable name can be extracted.

Greetings,
Maxime.


signature.asc
Description: This is a digitally signed message part

Re: Guix wiki

[Maxime Devos]

Attila Lendvai schreef op ma 11-04-2022 om 06:49 [+]:
> if someone wants to use guix as a platform for reproducible builds
> of go projects (independent of guix revisions), then a package
> definitions is needed that refers to specific versions of its
> dependencies.
> 
> currently it's not possible to open a new isolated scheme module,
> and algorithmically define/import the entire transitive closure of
> the dependencies of a go project, because they may clash in the
> package-name namespace with projects already defined elsewhere in
> guix.

Suggestion: clashing names is not a problem, as long as the final
package to build actually has an unambigious name.  Also, it is not
necessary to actually give these intermediate packages a variable name,
maybe do something like

(define-module (gnu packages ...))
(define-public foo [... a conventional guix package definition ...])

(define-module (my-reproducibility-test)
  #:use-module (gnu packages ...))

(define %version-pins ; <-- TODO: teach "guix import go --pin-versions" to 
produce this kind of structure?
  ;; package name / version / hash
  '(("go-github-com-operatorfoundation-shapeshifter-transports" "0.1.2" 
"0f1hzhk3q2fgqdg14zlg3z0s0ib1y9xwj89qnjk95b37zbgqjgsb")
[...]))

(define pin-input
  (match-lambda
((label package . rest)
 (cons* label (pin package) rest

(define pin
  (mlambda (package)
If the package name does not occur in %version-pins --> return package 
unchanged.
Otherwise, return
(package
  (inherit package)
  (version the new version)
  (source (origin (inherit (package-source package))
 an appropriately adjusted commit
 the new hash))
  ;; TODO: other versions of dependencies might need extra dependencies
  (inputs (map pin-input package))
  (native-inputs (map pin-input package))
  (propagated-inputs (map pin-input package

(define-public my-reproducibility-test-foo
  (package
(inherit (pin foo))
(name "foo-as-found-elsewhere")))

Does that suit your purposes?

Greetings,
Maxime.


signature.asc
Description: This is a digitally signed message part

Re: Guix wiki

[Attila Lendvai]

here's an example of what i would add to the wiki, because i think all other 
options are worse (but correct me if i'm wrong!):

open a page about highlevel design goals/issues, and then open an entry for the 
problem that packages have two names in two namespaces: the scheme 
module/variable namespace, and the guix package name namespace.

these names are pretty much independent from each other (modulo some 
conventions), and this is an issue for the importers. more specifically the go 
importer, that currently needs scheme variable names to refer to the identified 
dependencies, while it can only look up the package objects. these objects know 
nothing about the scheme variables they are stored in.

if someone wants to use guix as a platform for reproducible builds of go 
projects (independent of guix revisions), then a package definitions is needed 
that refers to specific versions of its dependencies.

currently it's not possible to open a new isolated scheme module, and 
algorithmically define/import the entire transitive closure of the dependencies 
of a go project, because they may clash in the package-name namespace with 
projects already defined elsewhere in guix.

--
• attila lendvai
• PGP: 963F 5D5F 45C7 DFCD 0A39
--
“It's better to know nothing than to know what ain't so.”
— Josh Billings

Re: Guix wiki

[Ludovic Courtès]

Hi,

Matt  skribis:

>   On Tue, 11 Jan 2022 18:18:25 -0500 Ricardo Wurmus  
> wrote 
>
>  > This is where we disagree.  I’ve wasted so much time in my life
>  > following outdated or wrong instructions on forums or wikis.  I really
>  > don’t want to see anything half-baked anywhere near this project.  There
>  > are few things that frustrate me more than well-meaning but misleading
>  > advice.
>  
> Do you know that the libreplanet wiki is linked to from the main Guix page?  
> https://guix.gnu.org/ > Help > Wiki

We are aware of this wiki; it has its uses, such as synchronizing for
FOSDEM, GSoC, and other events, but we never intended to use it for
documentation.

It’s unfortunate that your reply to Ricardo dismisses their advice.  It
really boils down to this: read bits of the manual and cookbook that
matter to your use cases, articulate what you think is missing or poorly
structured, and propose changes or new text.

It’s much easier to make progress looking at concrete, focused changes
than in the abstract.

Thanks in advance,
Ludo’.

Re: Guix wiki

[Luis Felipe]

On Wednesday, January 12th, 2022 at 3:51 AM, Matt  wrote:

> The reality is that wikis can be helpful and they can be misleading. I don't 
> think anyone is under the impression that they will write and maintain 
> themselves.
> 

> I'm not advocating for a wiki. I'm saying, there is one currently linked to 
> from the homepage. What should be done with it?
> 

> I'm willing to help maintain it.

Just wanted to add that the links to the Guix group on LibrePlanet were added 
to the website as part of issue #47555 (https://issues.guix.gnu.org/47555). 
Quoting the Help page (https://guix.gnu.org/en/help/), this was/is the intended 
purpose of the Wiki:

«The LibrePlanet Wiki provides a collaborative space for people to share 
additional information about the Guix project and its subprojects. It may 
contain help information, feature proposals, and notes about work in progress 
(among other things).»

And, being a wiki, I would expect its contents to be like sandcastles in a 
sandbox.

publickey - luis.felipe.la@protonmail.com - 0x12DE1598.asc
Description: application/pgp-keys


signature.asc
Description: OpenPGP digital signature

Re: Guix wiki

[André A . Gomes]

Attila Lendvai  writes:

> this sounds nice, but the reality is that nowadays reviewing and
> pushing commits can take weeks or even months without much feedback. i
> even have a fix for git-authenticate, coupled with tests that
> demonstrate a hole, and it's been open for months. i assume because of
> the lack of bandwidth from people who are in position to review and/or
> push it, but whatever the reason is, this is the case.
>
> the vision you are painting here is inspiring, but i think the Guix
> community is reaching a size where such an organizational structure is
> not facilitating the cooperation well enough. more and more random
> people will show up, with contributions of varying levels of
> quality. if it all goes through the current choke-points of the core
> (people, guix-devel, etc), then they will get overwhelmed, or at least
> will limit what could otherwise be achieved with more appropriate
> tools/processes.

You might have a point here, but I get the feeling that things are
slowly changing to address it.  Also, it's important to keep in mind
that the sporadic contributor will always be more scrutinised.

> random example: the readability of plain-text emails pouring into
> guix-patches, compared to e.g. threaded, formatted, and
> displayed-in-context comment threads in a tool like gitlab.

I don't see how gitlab would help.  Gnus, for instance, provides the
formatting you mention.


-- 
André A. Gomes
"Free Thought, Free World"

Re: Guix wiki

[Ricardo Wurmus]

Attila Lendvai  writes:

> random example: the readability of plain-text emails pouring into
> guix-patches, compared to e.g. threaded, formatted, and
> displayed-in-context comment threads in a tool like gitlab.
>
> i subscribed to guix-patches for a while, but it felt like noise.

I’m not subscribed to guix-patches.

Are you aware of https://issues.guix.gnu.org?

-- 
Ricardo

Re: Guix wiki

[Attila Lendvai]

what follows is some 0.02 from someone relatively new to Guix.


> > sending a patch to the manual is a way higher threshold than editing a
> > wiki, especially when it's someone's first contribution. and some
> > random, half-baked copy-paste doesn't belong in the manual, while it
> > may be very useful when found in a wiki using the search engine.
>
> This is where we disagree. I’ve wasted so much time in my life
> following outdated or wrong instructions on forums or wikis. I really
> don’t want to see anything half-baked anywhere near this project. There
> are few things that frustrate me more than well-meaning but misleading
> advice.


sure, this is a matter of taste.

although, it's one thing to get misguided with 1) informal
instructions, and another with 2) formal ones (i.e. a snippet of
runnable code that emits useful errors and backtraces when things go
wrong).

an obsolete instance of 2) can still be useful when all it needs is
just a small change to follow some renames.

ad-hoc example: a package definition demonstrates a complex technique,
but otherwise uses the obsolete pre-c-u-f merge input syntax, for
which the runtime warns/errors.


> I keep repeating myself: you don’t need to use debbugs. We do. Nor do


this is true to some extent when sending a one-shot patch to the
docs. but when i'm sending patchsets to the codebase, i do need to
learn at least the basics of debbugs. sorry for broadening the scope
here, but these are related.


> Before Guix I had never used Debbugs. I rarely ever contributed
> patches. I had no idea how to send patches via email. There was a time
> when I didn’t know that patches are generated with tools.


my point is that i know all these, and have been practicing them for
decades, and yet, contributing to Guix required a learning curve that
was higher than it's regularly expressed by people who are already used to it.

i do understand and accept the reasons (freedom, bootstrappability,
independence, etc), but i think the tools/infrastructure that Guix
uses for coordination is not very familiar to most programmers.


> No aspiring contributor needs to be fully formed before they are
> permitted to contribute. Get yourself a mentor within the project who
> can shepherd your contributions and make sure they find their way into
> the right files. Ping them if your contribution seems to have been
> forgotten.
>
> In my opinion, a public list of mentors that you can ask to charge of
> your contribution would be worth more than a mere info dumping site.


this sounds nice, but the reality is that nowadays reviewing and
pushing commits can take weeks or even months without much feedback. i
even have a fix for git-authenticate, coupled with tests that
demonstrate a hole, and it's been open for months. i assume because of
the lack of bandwidth from people who are in position to review and/or
push it, but whatever the reason is, this is the case.

the vision you are painting here is inspiring, but i think the Guix
community is reaching a size where such an organizational structure is
not facilitating the cooperation well enough. more and more random
people will show up, with contributions of varying levels of
quality. if it all goes through the current choke-points of the core
(people, guix-devel, etc), then they will get overwhelmed, or at least
will limit what could otherwise be achieved with more appropriate
tools/processes.

random example: the readability of plain-text emails pouring into
guix-patches, compared to e.g. threaded, formatted, and
displayed-in-context comment threads in a tool like gitlab.

i subscribed to guix-patches for a while, but it felt like noise.

--
• attila lendvai
• PGP: 963F 5D5F 45C7 DFCD 0A39
--
“Birds born in a cage think flying is an illness.”
— Alejandro Jodorowsky

Re: Guix wiki

[Ricardo Wurmus]

Matt  writes:

> My guess, as Guix is a package manager, there are two audiences:
> package users (end users) and package maintainers. I'm curious what
> degree of separation between those should exist for Guix.

On of the goals of the GNU project is to give users the tools to
liberate themselves from arbitrary restrictions.  The Hurd pretty much
does away with the concept of an all-powerful root user as the only
privileged account to alter settings such as network, file system
virtualization, drivers, etc.

Emacs is designed to be a collection of extensions.

Guile was designed to be the extension language for every part of the
GNU system that was still constrained by the dead systems programming
language C.

Likewise, Guix aims to give “end users” control over their software
environments and systems, privileges that used to be reserved for the
sysadmin class.  All design decisions in Guix are aimed at extending
privileges to users: package transformations, package inheritance,
building packages from JSON descriptions for those averse to Scheme,
per-user channels, time machine, an extensive API to build and export
systems, virtual machines, containers, environments, etc.

We don’t like to erect arbitrary boundaries between “end users” and
maintainers.  The concept of “maintainer” only ever has meaning in the
context of project management.  (Unlike nixpkgs, for example, we don’t
record package maintainers with package definitions.)

So, ideally, the information in the manual / cookbook will benefit all
users, no matter how deep they want to dive.  A single document cannot
accomplish this, which is why we recognize the existence of other GNU
manuals and link to them where possible.

-- 
Ricardo

Re: Guix wiki

[André A . Gomes]

zimoun  writes:

> Hi Tobias,
>
> On Wed, 12 Jan 2022 at 03:20, Tobias Geerinckx-Rice  wrote:
>
>> I'm disappointed by the ‘bikeshedding’ insult.  I really don't
>> care what you call it.
>
> 'insult' is a strong word and I am somehow hurt that you give me this
> intention.  I do not know what I did wrong --since we both agree we do
> not care about the name-- but apparently my contributions to these
> email lists lead to misunderstandings -- probably because my English
> is not good enough.  Therefore, I take a step back and some distance
> with this thread and many others.
>
>
>> >  - cathedral, as it is today
>>
>> I object to redefining loaded terms to promote it.
>
> ..and I already agreed that it was probably a wrong choice.

It seems that you're both are on the same page, and got too "excited"
about the wording.  Please don't draw more importance than it deserves.

Simon, I'm sure everyone is eager to listen to your insights.


-- 
André A. Gomes "Free Thought, Free World"

Re: Guix wiki

[zimoun]

Hi Tobias,

On Wed, 12 Jan 2022 at 03:20, Tobias Geerinckx-Rice  wrote:

> I'm disappointed by the ‘bikeshedding’ insult.  I really don't
> care what you call it.

'insult' is a strong word and I am somehow hurt that you give me this
intention.  I do not know what I did wrong --since we both agree we do
not care about the name-- but apparently my contributions to these
email lists lead to misunderstandings -- probably because my English
is not good enough.  Therefore, I take a step back and some distance
with this thread and many others.


> >  - cathedral, as it is today
>
> I object to redefining loaded terms to promote it.

..and I already agreed that it was probably a wrong choice.

Best regards,
simon

Re: Guix wiki

[Matt]

  On Tue, 11 Jan 2022 10:30:22 -0500 Tobias Geerinckx-Rice  
wrote 
 > Hullo Matt,
 > 
 > Matt 写道：
 > > I feel like it also says that community isn't important to us.
 > 
 > I understand how you could reach a flawed conclusion from a flawed 
 > assumption:
 > 
 > > Wikis are synonymous with community.
 > 
 > But it's still circular, wrong, and frankly quite offensive.


I didn't mean to say that you or the broader Guix community doesn't care. I can 
see how what I said was unclear and accused people of that. I'm sorry for that.

What I tried to say was *not* if someone values community that they must have a 
wiki. Instead, that a wiki is inherently based around community. If there's a 
wiki, there is implied community.  Of course, it's technically possible for 
someone to create, host, and maintain a wiki just for themselves. But given the 
options of not hosting, or using some other format (e.g. blog), the choice of a 
wiki strongly implies collaboration (which is the essence of community).

I was under the impression that the wiki linked to from the main page was *not* 
editable by non-FSF members. I was mistaken about that. If that were the case 
(non-editable), then I think it would reflect poorly.

I  tried to make the wiki more clear. I still think it's confusing for it to be 
there.

 > Guix cares about community very much.  Many of us care very little 
 > for wikis, having seen how they attract much outdated and 
 > incorrect information and spam.  Wikis are high-maintenance.
 
Given this situation, I see why.

 > I must say, the proponents of wikis have done an exceptionally 
 > poor job of representing them.  Yet we're supposed to be convinced 
 > that we're missing countless valuable contributions by people who 
 > can't be bothered to send a mail.

The reality is that wikis can be helpful and they can be misleading. I don't 
think anyone is under the impression that they will write and maintain 
themselves.

I'm not advocating for a wiki.  I'm saying, there is one currently linked to 
from the homepage. What should be done with it?

I'm willing to help maintain it.

Re: Guix wiki

[Matt]

  On Tue, 11 Jan 2022 18:18:25 -0500 Ricardo Wurmus  
wrote 

 > This is where we disagree.  I’ve wasted so much time in my life
 > following outdated or wrong instructions on forums or wikis.  I really
 > don’t want to see anything half-baked anywhere near this project.  There
 > are few things that frustrate me more than well-meaning but misleading
 > advice.
 
Do you know that the libreplanet wiki is linked to from the main Guix page?  
https://guix.gnu.org/ > Help > Wiki

I believe it proves your point. I was misled by its information. I'm not 
advocating for a wiki so much as a clear and easy path to contributing.  A wiki 
happens to be a common choice for that.

I updated it to try to remove the confusing content.

If it's not official and not wanted, I request removing it from the main page.

Re: Guix wiki

[Matt]

  On Tue, 11 Jan 2022 10:17:43 -0500 Ricardo Wurmus  
wrote 
 > 
 > Matt  writes:
 > 
 > > To me, it says something like, we don't actually care about your
 > > contribution: you have to literally buy in first.
 > 
 > No, you do not.
 
I stand corrected.  Luis Felipe kindly pointed out what I had overlooked.

https://lists.gnu.org/archive/html/guix-devel/2022-01/msg00194.html

 > I see a lot of emotional language here, but the fact is: you can
 > contribute to our documentation by sending your text.  It’s that
 > simple. 

I'm sorry if you felt accused. I can see how it might come across that way.  It 
would have been better for me to just ask if I was missing something (which I 
was).

 > Send an email to guix-devel or guix-patches with a suitable subject so
 > that it doesn’t get lost in a discussion and take it from there.
 > 
 > > I feel like it also
 > > says that community isn't important to us.
 > 
 > I do not share your interpretation of the situation.

I'm glad because that means we're in agreement now that I see my mistake. :)

Re: Guix wiki

[Tobias Geerinckx-Rice]

Hi Zimoun,

I'm disappointed by the ‘bikeshedding’ insult.  I really don't 
care what you call it.



 - cathedral, as it is today


I object to redefining loaded terms to promote it.

Kind regards,

T G-R


signature.asc
Description: PGP signature

Re: Guix wiki

[Matt]

  On Mon, 10 Jan 2022 03:29:35 -0500 Josua Stingelin  
wrote 

 > I've been following the gnunet for a while so I felt qualified to comment.
 > 
 > > Concern 1: guix will be soon be distributed over gnunet
 > Guix could provide an endpoint in the gnunet network for users that prefer to
 > use it. However there's no reason to prevent it from being accessible using 
 > the
 > current TCP/IP stack.
 > 
 > The goal of gnunet is to replace the TCP/IP stack. It is built as an overlay
 > and underlay network. It can run on TCP/IP but could also replace it. Every
 > application using TCP/IP would have to be converted to use gnunet or
 > gnunet would have to emulate TCP/IP. Until then they'll run in parallel.

Thanks for explaining.  

 > > Concern 5: having a wiki may confuse what the primary source of 
 > > documentation is (i.e. the manual)
 > > 
 > >   I'm not sure I understand why this is a problem. Of course,
 > >   confusion should be minimized.  But the primary source of
 > >   documentation should be the one that best helps the user.  Ideally,
 > >   that is the manual.  Is there a negative consequence for the primary
 > >   source not being the manual?  For example, how many of you have used
 > >   the Arch wiki to solve problems for something other than the Arch
 > >   system?  Is that a problem?
 > 
 > I suppose that depends on the user. As a new linux user I tended to only use
 > the information available for my distro. Only after knowing the differences
 > from the distros have I started to use a wider spectrum for information.
 > 
 > That may primarily be a question of the target audience for guix?

My guess, as Guix is a package manager, there are two audiences: package users 
(end users) and package maintainers. I'm curious what degree of separation 
between those should exist for Guix. 

 > > Concern 8: the manual should have all the examples necessary for people to 
 > > understand how to tweak things
 > > 
 > >   Agreed.  Contributing to documentation also shouldn't be as
 > >   difficult as it currently is, but here we are.  Let's figure it out
 > >   together. :)
 > 
 > What about an online editing interface (analogous to Wikipedia) where 
 > everyone
 > can make edit suggestions.  Optimally directly converted to a patch by the
 > software.  Changes to the cookbook would have to be merged by the maintainers
 > and the community based wiki could either have a group of editors or a
 > consensus based workflow.
 > 
 > 
 > Personally I believe having one resource for information to be the preferred
 > solution. Maybe the Gentoo wiki could be a source of inspiration on what we'd
 > like to achieve?  (https://wiki.gentoo.org/wiki/Main_Page)

There is currently a wiki.  I could see it being a sandbox for what the manual 
may need.  But I also see disdain towards wikis by some here that's not 
unreasonable.

Re: Guix wiki

[Ricardo Wurmus]

Attila Lendvai  writes:

> sending a patch to the manual is a way higher threshold than editing a
> wiki, especially when it's someone's first contribution. and some
> random, half-baked copy-paste doesn't belong in the manual, while it
> may be very useful when found in a wiki using the search engine.

This is where we disagree.  I’ve wasted so much time in my life
following outdated or wrong instructions on forums or wikis.  I really
don’t want to see anything half-baked anywhere near this project.  There
are few things that frustrate me more than well-meaning but misleading
advice.

The cookbook can have little vignettes on how to do this or that — a
note on how to debug an error, how to configure a certain tool (if the
way it’s done on Guix is special), etc — there is no need to write
full-blown tutorials, obviously.

> also note that i'm programming since i was a child, 30+ years now. at
> least half of it was part of opensource projects, and yet i had quite
> a learning curve getting to the point of submitting patches with any
> level of confidence (but not yet comfort).
>
> emails + debbugs + emacs + double-spaces + whatnot are all a cultural
> thing, and not necessarily simple for aliens, not at all. if you want,
> i can get into the details.

I keep repeating myself: you don’t need to use debbugs.  We do.  Nor do
you need to use Emacs.  (I do.)  You don’t need to use double spacing,
though someone is going to change it for you when applying your changes.

The requirements to contribute to the cookbook or manual are simple:
write text that is useful, correct, and readable, and have someone turn
it into the expected format for you.  If you’re a repeat contributor
your mentor may likely ask you on your next contributions to make a few
changes by yourself, so the learning curve is personalized.

Before Guix I had never used Debbugs.  I rarely ever contributed
patches.  I had no idea how to send patches via email.  There was a time
when I didn’t know that patches are generated with tools.

No aspiring contributor needs to be fully formed before they are
permitted to contribute.  Get yourself a mentor within the project who
can shepherd your contributions and make sure they find their way into
the right files.  Ping them if your contribution seems to have been
forgotten.

In my opinion, a public list of mentors that you can ask to charge of
your contribution would be worth more than a mere info dumping site.

-- 
Ricardo

Re: Guix wiki

[Attila Lendvai]

> > There is something here:
> > https://libreplanet.org/wiki/Group:Guix

[...]

> I was thrilled to see a wiki link on the homepage and disgusted to
> see that it didn't actually foster community. In fact, there's
> strife immediately within the "community" wiki, the simple fact it
> exists, let alone what it says. I think it would be better to have
> nothing linked from the homepage because 1) the current wiki is
> useless and 2) linking endorses what's there, including how it
> appears hostile to community.


FWIW, i had a similar experience when i came to Guix a few months ago:
i was thrilled that there was a wiki, and then i quickly got
disappointed that it's some shared something with little content
(which means that e.g. searching will bring up all kinds of unrelated
matches, etc).

i looked for the wiki because i wanted to add something useful to it
that i was searching for way too long, but then i ended up getting
dismayed and dropped the idea.

sending a patch to the manual is a way higher threshold than editing a
wiki, especially when it's someone's first contribution. and some
random, half-baked copy-paste doesn't belong in the manual, while it
may be very useful when found in a wiki using the search engine.

also note that i'm programming since i was a child, 30+ years now. at
least half of it was part of opensource projects, and yet i had quite
a learning curve getting to the point of submitting patches with any
level of confidence (but not yet comfort).

emails + debbugs + emacs + double-spaces + whatnot are all a cultural
thing, and not necessarily simple for aliens, not at all. if you want,
i can get into the details.

note that i'm not necessarily arguing for a wiki here, i understand
the concerns. i just want to draw attention that contributing to Guix,
and especially to the manual by a non-coder, is not at all as simple
as i see repeatedly expressed.

--
• attila lendvai
• PGP: 963F 5D5F 45C7 DFCD 0A39
--
Copying is not theft, and coercively excluding other humans from using 
knowledge is evil.

Re: Guix wiki

[zimoun]

Hi Tobias,

I agree with your words.  And probably my wrong choice of words to
convey my points.


On Tue, 11 Jan 2022 at 18:55, Tobias Geerinckx-Rice  wrote:

> >  - cathedral, as it is today
>
> This is revisionist.  The Bazaar model perfectly describes Guix,

Well, I do not think the Cookbook is a currently bazaar or a cookbook.
At least, not the kind of real world bazaar or cookbook I know. :-)


> where everyone is free to submit changes and have them critiqued
> and revised in public.  Even maintainers are expected to submit.
> Changes that meet $criteria are merged into a source tree
> immediately available to everyone.

I never said the contrary. :-)


> Guix has never used the Cathedral model, where patch submission
> and discussion happen behind closed doors, to be released unto the
> public as a revelation from on high.

I have never said the contrary. :-)

(For the record, GNU Emacs and GNU GCC were considered as Cathedral by
the book you are referencing.)


> ‘People push nontrivial changes without review’ was never a
> condition of the Bazaar model or what made it successful.  The
> book was based on LKML, for heaven's sake!  :-)

Whatever the name of ‘People push nontrivial changes without review’,
which is more or less my definition of a wiki.


> We can find a cute new name for what's being proposed in this
> thread (the Wailing Wall model?), but simply declaring ‘the Bazaar
> is called Cathedral now, change my mind’ can't work.

For sure, if you prefer another term, I am fine.  I will not bikeshed
on that. ;-)

In any case, it is not the core of my previous message, which appears
to me more important that the name for describing the way to
contribute to the documentation.  If you prefer the Wailing Wall,
fine. :-)


Cheers,
simon

Re: Guix wiki

[Jonathan McHugh]

Hi Matt,

Thanks for an interesting and thoughtful thread.

FYI, I am developing an interpreting application that will be mixing 
Emacs-Hyperboles tree orientated format with Gemini protocol's GemText format 
(as well as some classification approaches). Potentially it can (eventually) 
make a good fit for a wiki.

I will be presenting some aspects around it for Fosdem
=> https://fosdem.org/2022/schedule/event/minimalsyntaxes/

Kind regards,


Jonathan McHugh
indieterminacy@libre.brussels

January 11, 2022 3:24 PM, "Matt"  wrote:

>> There are definitely wikis which use fairly simple markup
> 
>> (e.g. markdown) and can usefully be read and updated online via a web
>> interface and git offline or online. The one I'm most familiar with is
>> ikiwiki (available in guix), though don't have a lot of experience
>> updating it via the web interface.
> 
> It looks like the web interface is simple yet sufficient, basically a text 
> box and then the buttons
> you'd expect: submit, preview, add/remove attachment. It uses the usual 
> markdown syntax and can
> support others using plugins.
> 
> https://ikiwiki.info/ikiwiki/formatting
> 
> The default style is pretty bare bones, but I imagine it could be made to 
> match the Guix theme.
> 
> Great suggestion!

Re: Guix wiki

[André A . Gomes]

Tobias Geerinckx-Rice  writes:

> Hi Simon, all,
>
> I'll give your long and thoughtful reply the attention it deserves
> when I have time, but there's another misleading tangent that has 
> bothered me (elsewhere) in this discussion:
>
>>  - cathedral, as it is today
>
> This is revisionist.  The Bazaar model perfectly describes Guix, where
> everyone is free to submit changes and have them critiqued and revised
> in public.  Even maintainers are expected to submit. Changes that meet
> $criteria are merged into a source tree immediately available to
> everyone.
>
> Guix has never used the Cathedral model, where patch submission and
> discussion happen behind closed doors, to be released unto the public
> as a revelation from on high.
>
> ‘People push nontrivial changes without review’ was never a condition
> of the Bazaar model or what made it successful.  The book was based on
> LKML, for heaven's sake!  :-)
>
> We can find a cute new name for what's being proposed in this thread
> (the Wailing Wall model?), but simply declaring ‘the Bazaar is called
> Cathedral now, change my mind’ can't work.

Tobias, I couldn't agree more!!!


-- 
André A. Gomes
"Free Thought, Free World"

Re: Guix wiki

[Tobias Geerinckx-Rice]

Hi Simon, all,

I'll give your long and thoughtful reply the attention it deserves 
when I have time, but there's another misleading tangent that has 
bothered me (elsewhere) in this discussion:



 - cathedral, as it is today


This is revisionist.  The Bazaar model perfectly describes Guix, 
where everyone is free to submit changes and have them critiqued 
and revised in public.  Even maintainers are expected to submit. 
Changes that meet $criteria are merged into a source tree 
immediately available to everyone.


Guix has never used the Cathedral model, where patch submission 
and discussion happen behind closed doors, to be released unto the 
public as a revelation from on high.


‘People push nontrivial changes without review’ was never a 
condition of the Bazaar model or what made it successful.  The 
book was based on LKML, for heaven's sake!  :-)


We can find a cute new name for what's being proposed in this 
thread (the Wailing Wall model?), but simply declaring ‘the Bazaar 
is called Cathedral now, change my mind’ can't work.


Kind regards,

T G-R


signature.asc
Description: PGP signature

Re: Guix wiki

[zimoun]

Hi Tobias, all,

On Tue, 11 Jan 2022 at 16:30, Tobias Geerinckx-Rice  wrote:

> Guix cares about community very much.  Many of us care very little
> for wikis, having seen how they attract much outdated and
> incorrect information and spam.  Wikis are high-maintenance.

I agree with these words…

> I must say, the proponents of wikis have done an exceptionally
> poor job of representing them.  Yet we're supposed to be convinced
> that we're missing countless valuable contributions by people who
> can't be bothered to send a mail.

…but as I tried to explain elsewhere [1], different interpretations for
the aim of this “Cookbook” seems floating around.

 - cathedral, as it is today
 - bazaar, as a wiki could be

Obviously, it is possible to participate to the cathedral; clone, tweak,
drop a patch, done.  All by email.  But somehow, it could appears a bit
rigid at first.  Imagine, (generic) you are fighting with new paradigm,
your distro is not working as expected, you do not understand what’s
going on, after some reading here or there, and several attempts, you
succeed!  Now, one advice you found was not working exactly and you
adapted it a bit.  I am doubtful that you will read how to contribute
and finally send a patch.  I think,

$ git log --format="%an" -- doc/guix-cookbook.texi \
  | sort | uniq -c | sort -n

makes my point. ;-)

Do not take me wrong, I am also on this side (accurate and maintained
documentation via review; something that might last) but it appears that
some people would also like half-baked poorly-maintained documentation
as a wiki could provide.

There is no conflict, IMHO, because the goals are different.  For
instance, EmacsWiki [2] saved me a lot of time, although information
there is often half-baked or poorly-maintained and back in time, it
helped me to then jump to the Emacs Manual, Emacs Lisp Manual and others.
Similarly for ArchWiki [3].

It is not because I would not personally contribute in feeding this that
this kind of material cannot be worth. :-)

Therefore, IMHO, the question is becoming: how to gather this kind of
material?  Because we have to admit that the rigid Cookbook via email
patches of texi file is a limited success for this bazaar goal.  An
official wiki is one idea; it raises where hosts it?  How maintains the
infra?  etc.

I proposed [1] a Planet, other proposed ’Awesome list’, and from my
experience, it could be a first step to collect.  Again, where hosts it?
How maintain it?

Other said, do we, as a project, officially support such documentation?
For sure, with one big warning that the material can be outdated, even
wrong.  Or do we consider that we have already enough in our plate and
many place can host unofficial such documentation?

I am fine with both. :-)

Last, for sure, I am not convinced that officially hosting a wiki would
automagically feed it after the buzz of novelty and the hosting cost is
not negligible.  That’s why I think an intermediary as Planet or Awesome
list is better; for the current resource we have at hand.

1: 

2: 
3: 


Cheers,
simon

Re: Guix wiki

[Luis Felipe]

Hi, Matt.

On Tuesday, January 11th, 2022 at 1:31 PM, Matt  wrote:

> There is something here:
> https://libreplanet.org/wiki/Group:Guix

> Good point and it's already linked from the Guix homepage. Trouble is, it 
> only seems editable by FSF associate members (which costs $120 or $60 for 
> students). Am I missing something?

You don't have to pay to create an account. You may be just seeing FSF's banner 
for is current campaign to get funding through memberships. Just close the 
banner and

1. Click the Login link.
2. Create a non-member account.

I'm not a member of FSF and I can edit the wiki.



publickey - luis.felipe.la@protonmail.com - 0x12DE1598.asc
Description: application/pgp-keys


signature.asc
Description: OpenPGP digital signature

Re: Guix wiki

[Tobias Geerinckx-Rice]

Hullo Matt,

Matt 写道：

I feel like it also says that community isn't important to us.


I understand how you could reach a flawed conclusion from a flawed 
assumption:



Wikis are synonymous with community.


But it's still circular, wrong, and frankly quite offensive.

Guix cares about community very much.  Many of us care very little 
for wikis, having seen how they attract much outdated and 
incorrect information and spam.  Wikis are high-maintenance.


I must say, the proponents of wikis have done an exceptionally 
poor job of representing them.  Yet we're supposed to be convinced 
that we're missing countless valuable contributions by people who 
can't be bothered to send a mail.


I'm not.

Kind regards,

T G-R


signature.asc
Description: PGP signature

Re: Guix wiki

[Ricardo Wurmus]

Matt  writes:

> To me, it says something like, we don't actually care about your
> contribution: you have to literally buy in first.

No, you do not.

I see a lot of emotional language here, but the fact is: you can
contribute to our documentation by sending your text.  It’s that
simple.  You don’t need an account on some platform; email is enough.

Send an email to guix-devel or guix-patches with a suitable subject so
that it doesn’t get lost in a discussion and take it from there.

> I feel like it also
> says that community isn't important to us.

I do not share your interpretation of the situation.

-- 
Ricardo

Re: Guix wiki

[Matt]

 > There are definitely wikis which use fairly simple markup
 > (e.g. markdown) and can usefully be read and updated online via a web
 > interface and git offline or online. The one I'm most familiar with is
 > ikiwiki (available in guix), though don't have a lot of experience
 > updating it via the web interface.

It looks like the web interface is simple yet sufficient, basically a text box 
and then the buttons you'd expect: submit, preview, add/remove attachment.  It 
uses the usual markdown syntax and can support others using plugins.

https://ikiwiki.info/ikiwiki/formatting/

The default style is pretty bare bones, but I imagine it could be made to match 
the Guix theme.

Great suggestion!

Re: Guix wiki

[Matt]

 > There is something here:
 > https://libreplanet.org/wiki/Group:Guix

Good point and it's already linked from the Guix homepage. Trouble is, it only 
seems editable by FSF associate members (which costs $120 or $60 for students). 
Am I missing something?

While that meets the technical requirement for a wiki, I don't think it meets 
the spirit: to be easily editable by anyone.  What message does that send to 
would-be contributors?

To me, it says something like, we don't actually care about your contribution: 
you have to literally buy in first. I feel like it also says that community 
isn't important to us. As an FSF member, I could modify the wiki.  However, I 
know that most people can't. That's the opposite of community.  To me, the 
libreplanet wiki is a non-starter.  I was thrilled to see a wiki link on the 
homepage and disgusted to see that it didn't actually foster community. In 
fact, there's strife immediately within the "community" wiki, the simple fact 
it exists, let alone what it says.  I think it would be better to have nothing 
linked from the homepage because 1) the current wiki is useless and 2) linking 
endorses what's there, including how it appears hostile to community.

I'm able to rationalize and understand that these messages are probably not 
what's intended. However, I think it important to share those reactions.

Re: Guix wiki

[Josua Stingelin]

Hi Matt,

Thanks for the summary!

Disclaimer: I'm currently not a guix user.
I've been following the gnunet for a while so I felt qualified to comment.

> Concern 1: guix will be soon be distributed over gnunet
> 
>   I'm not familiar with gnunet.  Has this come to fruition? Are the
>   two mutually exclusive? Is it not possible to host the same text
>   using both gnunet and www? If the www wiki would mirror the gnunet
>   wiki, is there something that prevents gnunet mirroring www?

Guix could provide an endpoint in the gnunet network for users that prefer to
use it. However there's no reason to prevent it from being accessible using the
current TCP/IP stack.

The goal of gnunet is to replace the TCP/IP stack. It is built as an overlay
and underlay network. It can run on TCP/IP but could also replace it. Every
application using TCP/IP would have to be converted to use gnunet or
gnunet would have to emulate TCP/IP. Until then they'll run in parallel.

> Concern 5: having a wiki may confuse what the primary source of documentation 
> is (i.e. the manual)
> 
>   I'm not sure I understand why this is a problem. Of course,
>   confusion should be minimized.  But the primary source of
>   documentation should be the one that best helps the user.  Ideally,
>   that is the manual.  Is there a negative consequence for the primary
>   source not being the manual?  For example, how many of you have used
>   the Arch wiki to solve problems for something other than the Arch
>   system?  Is that a problem?

I suppose that depends on the user. As a new linux user I tended to only use
the information available for my distro. Only after knowing the differences
from the distros have I started to use a wider spectrum for information.

That may primarily be a question of the target audience for guix?

> Concern 8: the manual should have all the examples necessary for people to 
> understand how to tweak things
> 
>   Agreed.  Contributing to documentation also shouldn't be as
>   difficult as it currently is, but here we are.  Let's figure it out
>   together. :)

What about an online editing interface (analogous to Wikipedia) where everyone
can make edit suggestions.  Optimally directly converted to a patch by the
software.  Changes to the cookbook would have to be merged by the maintainers
and the community based wiki could either have a group of editors or a
consensus based workflow.


Personally I believe having one resource for information to be the preferred
solution. Maybe the Gentoo wiki could be a source of inspiration on what we'd
like to achieve?  (https://wiki.gentoo.org/wiki/Main_Page)

Kind Regards,
Josua


signature.asc
Description: PGP signature

Re: Guix wiki

[Vincent Legoll]

Hello,

There is something here:
https://libreplanet.org/wiki/Group:Guix

-- 
Vincent Legoll

Re: Guix wiki

[Vagrant Cascadian]

On 2022-01-09, Matt wrote:
> Concern 7: the manual can easily be read and modified while offline
>
>   This is another good point. Things shouldn't be tied to the
>   internet.
>
>   Fortunately, most wikis allow users to download the wiki (apart from
>   tools like wget).
>
>   Unfortunately, the manual requires users to have a full system
>   install and either commit rights or an extended conversion in order
>   to modify.  To quote the Wikipedia on wikis,
>
>   "All that people require to contribute is a computer [including a
>   mobile device], Internet access, a web browser, and a basic
>   understanding of a simple markup language (e.g. MediaWiki markup
>   language)"

There are definitely wikis which use fairly simple markup
(e.g. markdown) and can usefully be read and updated online via a web
interface and git offline or online. The one I'm most familiar with is
ikiwiki (available in guix), though don't have a lot of experience
updating it via the web interface.


live well,
  vagrant


signature.asc
Description: PGP signature

Guix wiki

[Matt]

nual would require far less work from our small pool of 
experts to maintain than a wiki

  This is a great point. People who can maintain the codebase and
  aren't interested in documentation shouldn't have to maintain a
  wiki.  It's a bad idea to split attention.

  Has the pool of Guix experts grown since 2015?

  Also what's meant by maintain?  Author or administer?

  The original author of the 2015 post was "more than happy to help
  maintain a Guix wiki [and], if needed, would be happy to host it
  somewhere."

  There currently exist two unofficial Guix wikis:

  - https://guix.miraheze.org/wiki/Main_Page
  - https://github.com/SystemCrafters/wiki-site

  I would gladly contribute to maintaining the quality of the
  writing. That makes at least 3 admins and 4 contributors.

Concern 7: the manual can easily be read and modified while offline

  This is another good point. Things shouldn't be tied to the
  internet.

  Fortunately, most wikis allow users to download the wiki (apart from
  tools like wget).

  Unfortunately, the manual requires users to have a full system
  install and either commit rights or an extended conversion in order
  to modify.  To quote the Wikipedia on wikis,

  "All that people require to contribute is a computer [including a
  mobile device], Internet access, a web browser, and a basic
  understanding of a simple markup language (e.g. MediaWiki markup
  language)"

Concern 8: the manual should have all the examples necessary for people to 
understand how to tweak things

  Agreed.  Contributing to documentation also shouldn't be as
  difficult as it currently is, but here we are.  Let's figure it out
  together. :)

* Footnotes

[fn:1] https://lists.gnu.org/archive/html/guix-devel/2015-09/msg00182.html