Re: [GNUnet-developers] New README.md and Github

[Nils Gillmann]

Florian Dold transcribed 14K bytes:
> I agree that we should not encourage or endorse using proprietary code
> hosting sites such as GitHub. I'm strongly against accepting contributions
> on GitHub. Even if the Gentoo project decided to do that, it remains a bad
> idea. The furthest we could go is have a read-only mirror with issues, pull
> requests etc. disabled, just for better visibility, though some might even
> object to that.
> 
> I'd even go further and say that the current README should feature more
> prominently that we do development in our own git repo and bug tracker, so
> that nobody confuses some fork on GitHub for the real thing.
> 
> Git is a distributed version control system, we don't require gitolite
> access to accept contributions.
> 
> However according to the GNU coding standards, there should be a README and
> INSTALL file. GNUnet's README is IMHO rather intimidating for beginners,
> and I feel that the README content/structure proposed by dvn is easier to
> digest.
> 
> So I'd encourage dvn's efforts to make the README more beginner friendly,

I just responded to an off-list message from Christian with an example of
someone I study with. I think they are younger than I am, and have some
but not too much experience with Free Software. Not a complete beginner.
I had to point them to the README file as a first step. Let just sink that
in for a moment. So before we take anything for granted we should try to
step down from our years and decades of experience. cgit is not "that easy"
for everyone. But finding a good adjustment or replacement where everyone
gets happy is also difficult. It is user experience. Onboarding. Maybe
instead of directly exposing the cgit first, we could have an
intermediate page with details, readme, URLs.

> and maybe move installation details to INSTALL (or refer to the manual
> instead of having another file).

Our "INSTALL" is generica I think, but we are free to change it...

> I don't have a strong opinion about markdown, but I'd prefer plaintext vs
> the proliferation of weird markup formats (guix uses org mode for their
> README, which I don't like either).
> 
> - Florian
> 
> On Wed, Aug 1, 2018, 17:14 Nils Gillmann <address@hidden> wrote:
> 
> > Hi Christian and Devan,
> >
> > here's my take on this:
> >
> > Christian Grothoff transcribed 4.8K bytes:
> > > Hi Devan,
> > >
> > > I don't quite see the point of the README.md: the existing README is
> > > perfectly readable for everybody, and having duplicate information is
> > > confusing (now one has to update two documents, and users may wonder
> > > which one they should read!).  I'd prefer to focus on having one
> > > document with good quality (and README is standard in GNU), and
> > > otherwise on having a good manual (texinfo and Web site).  If we want
> > > something that looks nice, effort should probably first be put into the
> > > Web site and the manual, where styling is actually effective.
> >
> > I know we share a dislike for Markdown. What Devan told me would be
> > more like an "nicer" README. The content would be the same - it could
> > even be generated. Pointless from our side, but there are already
> > project tracking gnunet on github, for example equalitie:
> > https://github.com/equalitie/gnunet-channels
> >
> > For ourselves it wouldn't be necessary, but consider it a community
> > service.
> >
> > > As for Github, as GNU we should never endorse or encourage users to use
> > > non-free software, and Github is non-free.  Hence there should not be an
> >
> > While I agree with this:
> > The assesment of GNU did not include lines about non-free software. As
> > long as the client side code is okay (does not load non-free code), it
> > is good enough for GNU.
> >
> > > official mirror there either. I also don't see a need, especially since
> > > as of yesterday we do have the new GNUnet server "running" (except no
> > > services are there yet, but configuration and migration can start
> > > "today"), so we finally do have redundant infrastructure (at least once
> > > we have it all setup properly).
> >
> > The point of the mirror/patch-grabbing location would be an
> > augmentation of our work, not a primary focus. Github hosts a large
> > community of developers which can not be ignored. Well okay, you can
> > ignore them.. but even when we get only a couple of contributions more
> > this way, it still counts. Yes, it is unfortunate that some (have to)
> > rely these services, but we can't get the whole world sign up on our
> > gitolite server. Email lists are more accessible, yes. But what I'm
> > getting at is that we lose nothing by testing this opportunity with
> > enough safety in place and well written guidelines.  We would not
> > *recommend* the use of github. We can even state as before that the
> > mailinglist is prefered and so forth.
> >
> > We don't get this with just a new server.
> >
> > > Happy hacking!
> > >
> > > Christian
> > >
> > >
> > > On 08/01/2018 04:42 PM, Devan Carpenter wrote:
> > > > Hi everyone -
> > > >
> > > > As you can see, I've pushed a "markdown" formatted README to the repo.
> > > > Please note this is not replacing the plaintext README file.
> > > >
> > > > My goal has been to make something that newcomers can read and use to
> > > > get started with GNUnet. Hopefully containing enough in 1 single
> > > > document to where they don't have to go searching for more
> > documentation
> > > > just to get installed and begin using GNUnet.
> > > >
> > > > Would love to hear feedback on this approach, and my attempt at it.
> > > > Also, the readme is far from complete, so please add to it.
> > > >
> > > > Now the next part of this message is about getting back on Github. I've
> > > > discussed this with a few others, and we think it could be beneficial
> > to
> > > > have an official mirror there. I think it could even be good to think
> > > > about moving in this direction:
> > https://wiki.gentoo.org/wiki/Gentoo_GitHub
> > > >
> > > > As long as we keep control of our own infrastructure which will remain
> > > > as the origin, I don't see any harm, and it could prove beneficial for
> > > > opening up to more developers, and interested individuals in general.
> > > >
> > > > I've created the README with rendering on Github in mind, and you can
> > > > see what it looks like here: https://github.com/dvn0/GNUnet
> > > >
> > > > Kind regards, and happy hacking
> > > > - dvn
> > > >
> > > >
> > > >
> > > > _______________________________________________
> > > > GNUnet-developers mailing list
> > > > address@hidden
> > > > https://lists.gnu.org/mailman/listinfo/gnunet-developers
> > > >
> > >
> >
> >
> >
> >
> > > _______________________________________________
> > > GNUnet-developers mailing list
> > > address@hidden
> > > https://lists.gnu.org/mailman/listinfo/gnunet-developers
> >
> > _______________________________________________
> > GNUnet-developers mailing list
> > address@hidden
> > https://lists.gnu.org/mailman/listinfo/gnunet-developers
> >

> _______________________________________________
> GNUnet-developers mailing list
> address@hidden
> https://lists.gnu.org/mailman/listinfo/gnunet-developers