Improving the Contributors Guide and LilyDev

classic Classic list List threaded Threaded
34 messages Options
12
Reply | Threaded
Open this post in threaded view
|

Improving the Contributors Guide and LilyDev

Paul Morris
Hello dev list,

Below are some notes I made as I worked with the contributor’s guide and LilyDev in recent months.  This started with minor things and grew from there.  They represent my view as a novice who is basically learning git and the command line as I go.  I found the learning curve pretty steep so even little things that make things easier would help.

I was planning on preparing patches for some of these items when I can get to it, others are suggestions and possible topics for discussion.  Janek’s interest in working on this inspired me to go ahead and type it up.

-Paul


A. Suggestions for LilyDev3:

Make nano the default editor for git, git-cl, and anywhere else needed.  This might be the simplest single thing that would improve the learning curve.  Those who like another more advanced editor like vim will likely know how to set it as their default.  (And/or in the CG walk the reader through the steps to change the editor settings.)

The indicator of the current git branch (in the command line prompt) is not set up in the .bashrc file as it says it is in CG.  This should already be set up.  See CG 3.2.1 Configuring Git, where it says:
  Finally, and in some ways most importantly,
  let’s make sure that we know what branch we’re on.
  If you’re not using LilyDev, add this to your ‘~/.bashrc’:
  export PS1="\u@\h \w\$(__git_ps1)$ "

Add to LilyDev a text editor that has code highlighting (one that's simpler than emacs).  For example LilyDev2 had geany and gedit but LilyDev3 doesn't.  (Or at least suggest some as recommended optional installs.)

Automatic formatting/indenting of C++ files currently doesn't work "out of the box” and there’s no easy way to manually get it to work.  Artistic Style 2.02 is required for LilyPond’s fixcc.py but LilyDev3 has 2.01, which is the version provided by Debian and the only version available through apt-get.  Version 2.02 is no longer available from SourceForge.  Possible solution: make fixcc.py work with Artistic Style 2.01 (Federico wrote that LilyDev will provide the default Debian version of Artistic Style so that rules out upgrading it to 2.02.)  (Another possible solution: does LilyPond need its own formatting style or would the GNU one work fine and avoid this maintenance/overhead?)


B. CG Notes

CG 2.1 Installing LilyDev in VirtualBox
Just for extra clarity, change:
"Click the browse icon and locate the LilyDev disk image…"
To:
"Click the browse icon and locate the LilyDev disk image file (the .iso file) that you downloaded…"

CG 3.3.4 Making Patches
"git format-patch origin" doesn't work if you type it in literally, but gives "ambiguous argument 'origin' " message.  Change it to "git format-patch origin/master" which I assume is the most common case.

CG 3.3.4 duplication typo under git-cl configuration:
  2. Move into the top source directory and then configure git cl with the following commands:
  3. Move into the top source directory and then configure git cl with the following commands:

CG 3.3.4 I think "git-cl install" should go elsewhere, where setup is covered, especially since it's already installed on LilyDev.

CG 3.3.4 git-cl configuration
add how to set the EDITOR variable for git cl, namely:
export EDITOR=/usr/bin/nano

Somewhere document how to access ~/.bashrc ( such as "nano ~/.bashrc" ) to see what environment variables are set, etc.

In general avoid having sections that basically repeat each other in different ways, for example, consider merging:
1. Git for the impatient (3.2.2) and Basic Git procedures (3.3)
2. Compiling with LilyDev (2.3) and Compiling (4.x)


C. A Few General thoughts FWIW:

Since those working on the documentation, website, or even source code may not be programmers but they still have to learn how to use git etc. keep non-programmers in mind as a primary audience for the CG.  For example:

Assume the reader is using LilyDev.  Those that aren't using LilyDev will have more experience and need less from the CG, so better to pitch things to those who need the most help.

The reader may need some help with certain command line tasks.  Go ahead and provide the literal command to type in when it is easy to do so, rather than assume the reader knows it already or should go look it up somewhere else.  (For example how to change the default editor.)



_______________________________________________
lilypond-devel mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: Improving the Contributors Guide and LilyDev

David Kastrup

Two notes:

Paul Morris <[hidden email]> writes:

> CG 3.3.4 Making Patches
> "git format-patch origin" doesn't work if you type it in literally,
> but gives "ambiguous argument 'origin' " message.

Shouldn't happen unless you managed to create either a local branch
named "origin" or a file with that name in the current directory.

> CG 3.3.4 git-cl configuration
> add how to set the EDITOR variable for git cl, namely:
> export EDITOR=/usr/bin/nano

Nano does not offer point-and-click in connection with LilyPond I think.

--
David Kastrup

_______________________________________________
lilypond-devel mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: Improving the Contributors Guide and LilyDev

Urs Liska


Am 04.05.2015 um 00:15 schrieb David Kastrup:
>> CG 3.3.4 git-cl configuration
>> >add how to set the EDITOR variable for git cl, namely:
>> >export EDITOR=/usr/bin/nano
> Nano does not offer point-and-click in connection with LilyPond I think.

I don't think so either.  But I don't see why that should matter here.
Without setting EDITOR to something different, e.g. nano, the user will
be facing vi during the submission process. And for most of the new
people this is really frightening. So this is actually important
information. (Hm, I would have sworn that I had added that information -
immediately after my first submission).

Urs

_______________________________________________
lilypond-devel mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: Improving the Contributors Guide and LilyDev

Carl Sorensen-3
In reply to this post by Paul Morris


On 5/3/15 4:09 PM, "Paul Morris" <[hidden email]> wrote:

I think that it would be great to have you prepare patches for the CG.
The CG is the least-reviewed manual in our set, so it's probably the
easiest manual for which to get patches approved.



>
>A. Suggestions for LilyDev3:

All of these suggestions would actually probably be for LilyDev4.  I'm not
sure that we will make another release of LilyDev3.  But if we did, I'm
still happy to host it.

>(And/or in the CG walk the reader through the steps to change the editor
>settings.)

This is an immediately-accessible thing to do.

>
>The indicator of the current git branch (in the command line prompt) is
>not set up in the .bashrc file as it says it is in CG.  This should
>already be set up.  See CG 3.2.1 Configuring Git, where it says:
>  Finally, and in some ways most importantly,
>  let¹s make sure that we know what branch we¹re on.
>  If you¹re not using LilyDev, add this to your Œ~/.bashrc¹:
>  export PS1="\u@\h \w\$(__git_ps1)$ "

Personally, I'd love to see a patch for this in the CG (and it would be
nice to have it in LilyDev out of the box).

>
>Add to LilyDev a text editor that has code highlighting (one that's
>simpler than emacs).  For example LilyDev2 had geany and gedit but
>LilyDev3 doesn't.  (Or at least suggest some as recommended optional
>installs.)

vim has code highlighting, and it is simpler than emacs in my opinion.
But I've been using it for 30 years, since I started with vi.

A CG entry that would tell how to install geany and/or gedit would
certainly be helpful.


>  (Another possible solution: does LilyPond need its own formatting style
>or would the GNU one work fine and avoid this maintenance/overhead?)

GNU's formatting style is less specific in the form of tabs/spaces, IIRC.
We've had this discussion, and I believe it's a good idea to exclude tabs,
and only use spaces in the source code.  astyle isn't needed if you are
careful with your editing and match the existing code. If you make a
mistake, it will be pointed out in review, and it's simple to fix it.

>
>
>B. CG Notes

Your notes on the CG are excellent in general.  I hope you will prepare
some patches!

>
>In general avoid having sections that basically repeat each other in
>different ways, for example, consider merging:
>1. Git for the impatient (3.2.2) and Basic Git procedures (3.3)

There are reasons (perhaps historical) for this duplication.  3.2.2 is
supposed to be briefer than 3.3.

>2. Compiling with LilyDev (2.3) and Compiling (4.x)

2.3 is about getting it set up with LilyDev.  4.x is about general work
whether with or without LilyDev.  We are much stronger about recommending
the use of LilyDev than we were when the CG was originally written, so
perhaps it's time to make a change here.

>
>
>C. A Few General thoughts FWIW:
>
>Since those working on the documentation, website, or even source code
>may not be programmers but they still have to learn how to use git etc.
>keep non-programmers in mind as a primary audience for the CG.  For
>example:
>
>Assume the reader is using LilyDev.  Those that aren't using LilyDev will
>have more experience and need less from the CG, so better to pitch things
>to those who need the most help.

I'm not sure I agree with this.  The CG is the only place in the manuals
that we provide help for those who are not using LilyDev.  And there are
some quirks of LilyPond that need to be part of the docs in my opinion.

I don't have a particular patch to comment on here, so I can only deal in
generalities.  But maybe we have a chapter that is something about
"Developing without LilyDev".

We certainly want to make the CG accessible for new users/developers.  But
we also want to have the CG useful for old developers and those
experienced with other software development environments.   Perhaps we
need to clarify these two different use cases, and separate them out more
carefully in the CG.  But IMO we need to avoid making the CG only useful
for newbies.

The CG has historically had a much less stringent editorial review
process.  Basically we said to developers "If there's something you think
should go in the CG, put it there."  Perhaps it's time to be more
selective, and see how we can tailor a short, accessible section of the CG
for new users.  And then we could leave the other stuff in chapters that
are aimed at experienced developers.

Thanks again for looking at this.  Certainly improving the CG is an
important part of the health of LilyPond.

Carl

_______________________________________________
lilypond-devel mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: Improving the Contributors Guide and LilyDev

Graham Percival-3
On Mon, May 04, 2015 at 03:02:32AM +0000, Carl Sorensen wrote:
> >A. Suggestions for LilyDev3:
>
> All of these suggestions would actually probably be for LilyDev4.  I'm not
> sure that we will make another release of LilyDev3.  But if we did, I'm
> still happy to host it.

If somebody is available and interested in preparing lilydev4, I
suggest splitting the list of improvements into lilydev4-stuff and
CG-stuff.


> >(And/or in the CG walk the reader through the steps to change the editor
> >settings.)
>
> This is an immediately-accessible thing to do.

Yes, although the editor settings can be done in advance in
lilydev4.  (I believe that /etc/skel/ is the place to look at, but
I know that somebody already figured this out and it wasn't me)

The CG could also have a section for "turning a typical ubuntu
installation into lilypond development-ready" (a shorter name
would be better), which gives details about this, setting PS1,
etc.  But ideally LilyDev4 should have as much as possible done in
advance, so that interested contributors can jump into
contributing.


> >In general avoid having sections that basically repeat each other in
> >different ways, for example, consider merging:
> >1. Git for the impatient (3.2.2) and Basic Git procedures (3.3)
>
> There are reasons (perhaps historical) for this duplication.  3.2.2 is
> supposed to be briefer than 3.3.

The main reason is that when I wrote 3.2.2, I forgot that 3.3
existed.  Either that, or I thought that 3.3 was too long.  I
forget which.

Either way, I don't think we need both sections.

> >2. Compiling with LilyDev (2.3) and Compiling (4.x)
>
> 2.3 is about getting it set up with LilyDev.  4.x is about general work
> whether with or without LilyDev.  We are much stronger about recommending
> the use of LilyDev than we were when the CG was originally written, so
> perhaps it's time to make a change here.

I think it's worth keeping a section about compiling for
non-lilydev, but perhaps something like "Advanced unix compiling"
(again, bad name) would be better.  Basically, make sure that 4.x
is clearly about general work.
(as an advanced Linux user, I would be annoyed if I had to wade
through lots of hand-holding in a discussion about how to compile
an open source project)


> We certainly want to make the CG accessible for new users/developers.  But
> we also want to have the CG useful for old developers and those
> experienced with other software development environments.   Perhaps we
> need to clarify these two different use cases, and separate them out more
> carefully in the CG.  But IMO we need to avoid making the CG only useful
> for newbies.

Yes.

> Thanks again for looking at this.  Certainly improving the CG is an
> important part of the health of LilyPond.

Absolutely!

- Graham

_______________________________________________
lilypond-devel mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: Improving the Contributors Guide and LilyDev

Federico Bruni
In reply to this post by Paul Morris
Hi Paul, thanks for the suggestions.

As Debian Jessie was released few days ago, I was thinking about a new
LilyDev.
I think I'll first upgrade to a more recent version of live-build and then
add the modifications you are suggesting.

2015-05-04 0:09 GMT+02:00 Paul Morris <[hidden email]>:

> A. Suggestions for LilyDev3:
>
> Make nano the default editor for git, git-cl, and anywhere else needed.
> This might be the simplest single thing that would improve the learning
> curve.  Those who like another more advanced editor like vim will likely
> know how to set it as their default.  (And/or in the CG walk the reader
> through the steps to change the editor settings.)
>
>
I just need to add an EDITOR variable in .bashrc. Currently there's only
LYEDITOR, which is for PDF point-and-click:
https://github.com/fedelibre/LilyDev/blob/master/config/includes.chroot/etc/skel/.bashrc#L122


> The indicator of the current git branch (in the command line prompt) is
> not set up in the .bashrc file as it says it is in CG.  This should already
> be set up.  See CG 3.2.1 Configuring Git, where it says:
>   Finally, and in some ways most importantly,
>   let’s make sure that we know what branch we’re on.
>   If you’re not using LilyDev, add this to your ‘~/.bashrc’:
>   export PS1="\u@\h \w\$(__git_ps1)$ "
>
>
Nice, I didn't know that! I'll add it.


> Add to LilyDev a text editor that has code highlighting (one that's
> simpler than emacs).  For example LilyDev2 had geany and gedit but LilyDev3
> doesn't.  (Or at least suggest some as recommended optional installs.)
>
>
Ok, I can add one of those, probably Geany.
(I tried to keep the size of ISO as smaller as possible.)



> Automatic formatting/indenting of C++ files currently doesn't work "out of
> the box” and there’s no easy way to manually get it to work.  Artistic
> Style 2.02 is required for LilyPond’s fixcc.py but LilyDev3 has 2.01, which
> is the version provided by Debian and the only version available through
> apt-get.  Version 2.02 is no longer available from SourceForge.  Possible
> solution: make fixcc.py work with Artistic Style 2.01 (Federico wrote that
> LilyDev will provide the default Debian version of Artistic Style so that
> rules out upgrading it to 2.02.)  (Another possible solution: does LilyPond
> need its own formatting style or would the GNU one work fine and avoid this
> maintenance/overhead?)
>

Jessie has version 2.04:
https://packages.debian.org/jessie/astyle

Is it ok?
_______________________________________________
lilypond-devel mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: Improving the Contributors Guide and LilyDev

Federico Bruni
2015-05-04 18:32 GMT+02:00 Federico Bruni <[hidden email]>:

> As Debian Jessie was released few days ago, I was thinking about a new
> LilyDev.
> I think I'll first upgrade to a more recent version of live-build and then
> add the modifications you are suggesting.
>

I have a question: does anybody use LilyDev as live os (i.e. without
installing)? Or most of you installs the system in a virtual machine?
I'm asking this because I'd prefer not downloading the git repositories
during the build of ISO images, in order to reduce the size and the build
time of the ISO (for my updates and tests).

So I'd rather put a script to download the repository when the user logs in
for the first time.
What do you think?

The problem is that lilypond-git takes a lot to download.
_______________________________________________
lilypond-devel mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: Improving the Contributors Guide and LilyDev

Phil Holmes
----- Original Message -----
From: "Federico Bruni" <[hidden email]>
To: "Paul Morris" <[hidden email]>
Cc: "LilyPond Development Team" <[hidden email]>
Sent: Monday, May 04, 2015 6:19 PM
Subject: Re: Improving the Contributors Guide and LilyDev


> 2015-05-04 18:32 GMT+02:00 Federico Bruni <[hidden email]>:
>
>> As Debian Jessie was released few days ago, I was thinking about a new
>> LilyDev.
>> I think I'll first upgrade to a more recent version of live-build and
>> then
>> add the modifications you are suggesting.
>>
>
> I have a question: does anybody use LilyDev as live os (i.e. without
> installing)? Or most of you installs the system in a virtual machine?
> I'm asking this because I'd prefer not downloading the git repositories
> during the build of ISO images, in order to reduce the size and the build
> time of the ISO (for my updates and tests).
>
> So I'd rather put a script to download the repository when the user logs
> in
> for the first time.
> What do you think?


Years ago I started by (accidentally) using it as a live OS.  It's a useless
way of trying to use it.  I wouldn't bother to try to support it.

--
Phil Holmes


_______________________________________________
lilypond-devel mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: Improving the Contributors Guide and LilyDev

Carl Sorensen-3
In reply to this post by Federico Bruni
On 5/4/15 11:19 AM, "Federico Bruni" <[hidden email]> wrote:
>So I'd rather put a script to download the repository when the user logs
>in
>for the first time.
>What do you think?

Isn't that the way it works right now?  If not, it certainly should.

There should be a script that configures git properly (i.e. with user name
and user email) and then clones the lilypond repository.

Thanks,

Carl


_______________________________________________
lilypond-devel mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: Improving the Contributors Guide and LilyDev

Wols Lists
In reply to this post by Carl Sorensen-3
On 04/05/15 04:02, Carl Sorensen wrote:
>> 2. Compiling with LilyDev (2.3) and Compiling (4.x)
> 2.3 is about getting it set up with LilyDev.  4.x is about general work
> whether with or without LilyDev.  We are much stronger about recommending
> the use of LilyDev than we were when the CG was originally written, so
> perhaps it's time to make a change here.
>
Am I right here? Is lilydev a debian-based virtual machine. I absolutely
DO NOT get on with Debian based distros. SuSE and gentoo are my thing,
I've tried Debian, Mint, Ubuntu, dunno what else ... if it's
debian-based I hated it. I don't know why, I didn't get on with Red Hat
either, despite SuSE and RH being rpm-based.

(Actually, I started using gentoo, because the latest SuSE was not
sufficiently up-to-date to compile a development copy of lilypond! :-)

But anyways, the main point of this email is to point out that pushing
debian could cost you developers - I don't know how many people like me
there are out there, but if I have to use a debian-based system my
reaction is likely to be "thanks but no thanks". (That said, I think a
ready-prepped virtual machine is a very good idea, just don't assume
"one size fits all")

Cheers,
Wol

_______________________________________________
lilypond-devel mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: Improving the Contributors Guide and LilyDev

James Lowe
On 04/05/15 22:39, Wols Lists wrote:

> On 04/05/15 04:02, Carl Sorensen wrote:
>>> 2. Compiling with LilyDev (2.3) and Compiling (4.x)
>> 2.3 is about getting it set up with LilyDev.  4.x is about general work
>> whether with or without LilyDev.  We are much stronger about recommending
>> the use of LilyDev than we were when the CG was originally written, so
>> perhaps it's time to make a change here.
>>
> Am I right here? Is lilydev a debian-based virtual machine. I absolutely
> DO NOT get on with Debian based distros. SuSE and gentoo are my thing,
> I've tried Debian, Mint, Ubuntu, dunno what else ... if it's
> debian-based I hated it. I don't know why, I didn't get on with Red Hat
> either, despite SuSE and RH being rpm-based.
>
> (Actually, I started using gentoo, because the latest SuSE was not
> sufficiently up-to-date to compile a development copy of lilypond! :-)
>
> But anyways, the main point of this email is to point out that pushing
> debian could cost you developers - I don't know how many people like me
> there are out there, but if I have to use a debian-based system my
> reaction is likely to be "thanks but no thanks". (That said, I think a
> ready-prepped virtual machine is a very good idea, just don't assume
> "one size fits all")
>
> Cheers,
> Wol
>

LilyDev has been Ubuntu-based (which is Debian righht?) since I started
the project (and used it to do most of the patch testing) 4 or so years
ago when it was LilyDev 1.0. I moved to just building locally once I was
comfortable with it but kept updating it for others. I haven't been
responsible for LilyDev since the last or so version of it.

The idea was that it was something easy to use out of the gate for those
that perhaps didn't 'do' Linux. But mainly because there were simple
tools to create Live images.

However at the time it was something like three clicks and a bit of time
to create a Live Image, very little effort. I'm not sure how easy it is
now or how simple the other Distros you mention are to create live images.

Besides, I think if a potential developer is 'into' caring about the
distro of LilyDev - you don't really state what your beef is (I don't
actually care), please consider that it is likely that:

1. They don't need lilydev
2. They are competent enough to set up their own 'VM' for whatever build
env they are comfortable with themselves.

Mind you, if you wanted to create a live ISO for LilyPond yourself (and
help maintain it) I am sure that no one will complain about that. It's
something that we don't tend up to update that often.

James






_______________________________________________
lilypond-devel mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: Improving the Contributors Guide and LilyDev

David Kastrup
In reply to this post by Wols Lists
Wols Lists <[hidden email]> writes:

> On 04/05/15 04:02, Carl Sorensen wrote:
>>> 2. Compiling with LilyDev (2.3) and Compiling (4.x)
>> 2.3 is about getting it set up with LilyDev.  4.x is about general work
>> whether with or without LilyDev.  We are much stronger about recommending
>> the use of LilyDev than we were when the CG was originally written, so
>> perhaps it's time to make a change here.
>>
> Am I right here? Is lilydev a debian-based virtual machine. I absolutely
> DO NOT get on with Debian based distros. SuSE and gentoo are my thing,
> I've tried Debian, Mint, Ubuntu, dunno what else ... if it's
> debian-based I hated it. I don't know why, I didn't get on with Red Hat
> either, despite SuSE and RH being rpm-based.
>
> (Actually, I started using gentoo, because the latest SuSE was not
> sufficiently up-to-date to compile a development copy of lilypond! :-)
>
> But anyways, the main point of this email is to point out that pushing
> debian could cost you developers - I don't know how many people like me
> there are out there,

Judging from the success of Ubuntu, not a majority.  The package system
of Debian is mature, reliable and flexible and has been so for quite
long.  You stand a good chance of being able to use Debian-based
packages on a number of Debian-based distributions even outside of
"Ubuntu remixes".

Exchanging packages between two RPM-based distributions like SuSE and
RedHat is not likely to work.  So with RPM, you are catering for only
one of several minority systems.

> but if I have to use a debian-based system my reaction is likely to be
> "thanks but no thanks". (That said, I think a ready-prepped virtual
> machine is a very good idea, just don't assume "one size fits all")

The whole point of a ready-prepped virtual machine is to provide a
shrink-wrapped "one size" solution for people not into special
solutions, particularly users without a GNU/Linux background not wanting
to set up and maintain a native system.  If you have more special
desires, the source is there perfectly well.  There is little point in
catering for people like you who will set up their own system anyway.

I myself have never used a virtual system for development.  It never was
any problem for me: it would be more of a hassle for me to set up
virtual environments.

--
David Kastrup

_______________________________________________
lilypond-devel mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: Improving the Contributors Guide and LilyDev

Dan Eble
In reply to this post by Wols Lists
> But anyways, the main point of this email is to point out that pushing
> debian could cost you developers - I don't know how many people like me
> there are out there, but if I have to use a debian-based system my
> reaction is likely to be "thanks but no thanks". (That said, I think a

The data point I can contribute is that anything beats three days of installing Lilypond dependencies on OS X by trial and error with fink/homebrew/whatever.  VM FTW!

Dan


_______________________________________________
lilypond-devel mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: Improving the Contributors Guide and LilyDev

Carl Sorensen-3
On 5/4/15 4:25 PM, "Dan Eble" <[hidden email]> wrote:

>> But anyways, the main point of this email is to point out that pushing
>> debian could cost you developers - I don't know how many people like me
>> there are out there, but if I have to use a debian-based system my
>> reaction is likely to be "thanks but no thanks". (That said, I think a
>
>The data point I can contribute is that anything beats three days of
>installing Lilypond dependencies on OS X by trial and error with
>fink/homebrew/whatever.  VM FTW!

I used to have an OS/X setup for development, but I couldn't maintain it.
So now I use Frescobaldi on OS/X for production work, and do my
development in a LilyDev VM.

We're not forcing Debian/Ubuntu (as far as I can see, LilyDev3 is just
Debian, no Ubuntu involved).  We're just providing something that works
out of the box.

Thanks,

Carl


_______________________________________________
lilypond-devel mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: Improving the Contributors Guide and LilyDev

Paul Morris
In reply to this post by David Kastrup
> On May 3, 2015, at 6:15 PM, David Kastrup <[hidden email]> wrote:
>
>> CG 3.3.4 Making Patches
>> "git format-patch origin" doesn't work if you type it in literally,
>> but gives "ambiguous argument 'origin' " message.
>
> Shouldn't happen unless you managed to create either a local branch
> named "origin" or a file with that name in the current directory.

Ok, I’ll have to look into this further when I get a chance.  If “git format-patch origin” works for others on LilyDev then there’s no need to edit this.


> On May 3, 2015, at 9:02 PM, Urs Liska <[hidden email]> wrote:
>
> Am 04.05.2015 um 00:15 schrieb David Kastrup:
>>> CG 3.3.4 git-cl configuration
>>> >add how to set the EDITOR variable for git cl, namely:
>>> >export EDITOR=/usr/bin/nano
>> Nano does not offer point-and-click in connection with LilyPond I think.
>
> I don't think so either.  But I don't see why that should matter here. Without setting EDITOR to something different, e.g. nano, the user will be facing vi during the submission process. And for most of the new people this is really frightening. So this is actually important information.

Yep, having your keyboard suddenly stop working like you expect it to in the middle of creating your first commit or patch set can be rather maddening.  Also if you follow the CG you might set the editor for git to nano, but when you use git-cl you get vi again.  So I think the default LilyDev editor should be nano and also explain how to change it (for git-cl) in the CG.

(I assume there are other ways of getting point-and-click if needed.)

-Paul



_______________________________________________
lilypond-devel mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: Improving the Contributors Guide and LilyDev

Paul Morris
In reply to this post by Carl Sorensen-3
> On May 3, 2015, at 11:02 PM, Carl Sorensen <[hidden email]> wrote:
>
> I think that it would be great to have you prepare patches for the CG.
> The CG is the least-reviewed manual in our set, so it's probably the
> easiest manual for which to get patches approved.

Will do, once this discussion winds down, and maybe I’ll wait until the new LilyDev arrives.  (Well, I can definitely do the specific things I've identified, not sure I can take on larger scale edits at this point.)


>> (And/or in the CG walk the reader through the steps to change the editor
>> settings.)
>
> This is an immediately-accessible thing to do.

Yes, I’ve made a note to add this.


>> The indicator of the current git branch (in the command line prompt) is
>> not set up in the .bashrc file as it says it is in CG.  This should
>> already be set up.  See CG 3.2.1 Configuring Git, where it says:
>> Finally, and in some ways most importantly,
>> let¹s make sure that we know what branch we¹re on.
>> If you¹re not using LilyDev, add this to your Œ~/.bashrc¹:
>> export PS1="\u@\h \w\$(__git_ps1)$ "
>
> Personally, I'd love to see a patch for this in the CG (and it would be
> nice to have it in LilyDev out of the box).

This is actually already in the CG (well I guess it doesn’t spell out *how* to add that line to the ~/.bashrc file).


> A CG entry that would tell how to install geany and/or gedit would
> certainly be helpful.

Agreed (although if they’re preinstalled maybe it’s not needed…)


> GNU's formatting style is less specific in the form of tabs/spaces, IIRC.
> We've had this discussion, and I believe it's a good idea to exclude tabs,
> and only use spaces in the source code.  astyle isn't needed if you are
> careful with your editing and match the existing code. If you make a
> mistake, it will be pointed out in review, and it's simple to fix it.

Ok.  


> Your notes on the CG are excellent in general.  I hope you will prepare
> some patches!

Thanks!  Will do.


> 2.3 is about getting it set up with LilyDev.  4.x is about general work
> whether with or without LilyDev.  We are much stronger about recommending
> the use of LilyDev than we were when the CG was originally written, so
> perhaps it's time to make a change here.

Hmmm… maybe that’s what I’m noticing / picking up on?  It seems that some sections assume you’re using LilyDev while others don’t.  


>> C. A Few General thoughts FWIW:
>>
>> Since those working on the documentation, website, or even source code
>> may not be programmers but they still have to learn how to use git etc.
>> keep non-programmers in mind as a primary audience for the CG.  For
>> example:
>>
>> Assume the reader is using LilyDev.  Those that aren't using LilyDev will
>> have more experience and need less from the CG, so better to pitch things
>> to those who need the most help.
>
> I'm not sure I agree with this.  The CG is the only place in the manuals
> that we provide help for those who are not using LilyDev.  And there are
> some quirks of LilyPond that need to be part of the docs in my opinion.
>
> I don't have a particular patch to comment on here, so I can only deal in
> generalities.  But maybe we have a chapter that is something about
> "Developing without LilyDev".
>
> We certainly want to make the CG accessible for new users/developers.  But
> we also want to have the CG useful for old developers and those
> experienced with other software development environments.   Perhaps we
> need to clarify these two different use cases, and separate them out more
> carefully in the CG.  But IMO we need to avoid making the CG only useful
> for newbies.

Yes, I could have worded that better.  I didn’t mean to suggest to focus exclusively on newbies, just that both use cases should be covered, and err on the side of the newbies since they are new.  But then I would say that, being more of a newbie…  ;-)

Anyway, as you suggest, this is probably better discussed in terms of particulars, actual cases, rather than in generalities.

> The CG has historically had a much less stringent editorial review
> process.  Basically we said to developers "If there's something you think
> should go in the CG, put it there."  Perhaps it's time to be more
> selective, and see how we can tailor a short, accessible section of the CG
> for new users.  And then we could leave the other stuff in chapters that
> are aimed at experienced developers.

Maybe, although I think having separate sections that cover similar things at different experience levels is often not the best approach.  It can feel fragmented and unwieldy.  

I’d rather have something like occasional sidebars (or boxes with a different color background) that are labelled “for beginners” or “for more advanced users” or “for those not using LilyDev” (etc.) that separate out some content from the main text but keep it right there for when you need it.  Then there can be one “canonical” account of how to do something, but it is easy for readers to skip the parts that they don’t need and focus on those they do.  And newbies can learn more as they go if they want.  That’s my take anyway.

Of course in some cases it may make sense to just have a separate section.

> Thanks again for looking at this.  Certainly improving the CG is an
> important part of the health of LilyPond.

Glad to help,
-Paul


_______________________________________________
lilypond-devel mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: Improving the Contributors Guide and LilyDev

Paul Morris
In reply to this post by Federico Bruni
Hi Federico,

> On May 4, 2015, at 12:32 PM, Federico Bruni <[hidden email]> wrote:
>
> Hi Paul, thanks for the suggestions.
>
> As Debian Jessie was released few days ago, I was thinking about a new LilyDev.

Hey, that’s great timing!

> I think I'll first upgrade to a more recent version of live-build and then add the modifications you are suggesting.

Ok, thanks!  Something to consider for geany and gedit:

They both have highlighting for c++, .css, and .py files,
gedit also has it for .scm, .itexi, .itely, and .make files,
but geany doesn’t have it for these.
(And neither has it for .ly files.)


> Automatic formatting/indenting of C++ files currently doesn't work "out of the box” and there’s no easy way to manually get it to work.  Artistic Style 2.02 is required for LilyPond’s fixcc.py but LilyDev3 has 2.01, which is the version provided by Debian and the only version available through apt-get.  Version 2.02 is no longer available from SourceForge.  Possible solution: make fixcc.py work with Artistic Style 2.01 (Federico wrote that LilyDev will provide the default Debian version of Artistic Style so that rules out upgrading it to 2.02.)  (Another possible solution: does LilyPond need its own formatting style or would the GNU one work fine and avoid this maintenance/overhead?)
>
> Jessie has version 2.04:
> https://packages.debian.org/jessie/astyle <https://packages.debian.org/jessie/astyle>
>
> Is it ok?

It's definitely better.  The comment in fixcc.py is pretty insistent that it only works with astyle 2.02 so I think we'll need a tracker issue for updating fixcc.py to work with astyle 2.04 (but at least upgrading should be easier than downgrading).

Thanks for all your work on LilyDev,
-Paul


_______________________________________________
lilypond-devel mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: Improving the Contributors Guide and LilyDev

Paul Morris
> On May 4, 2015, at 9:10 PM, Paul Morris <[hidden email]> wrote:
>
> They both have highlighting for c++, .css, and .py files,
> gedit also has it for .scm, .itexi, .itely, and .make files,
> but geany doesn’t have it for these.
> (And neither has it for .ly files.)

This was from the default LilyDev2 with geany 0.18 and gedit 2.30.3
_______________________________________________
lilypond-devel mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: Improving the Contributors Guide and LilyDev

janek.lilypond
Hi all,

as I've already mentioned, I've already started working on a new
LilyDev.  I'm going to use tools that should make it easy to build
different versions of LilyDev (e.g. 32-bit and 64-bit, possibly also
based on different distros).

In order to reduce work duplication, I suggest to wait with further
discussion until I have a working "prototype", which I'll present to
you for evaluation.  Hopefully this will happen within a week from
now.

best,
Janek

_______________________________________________
lilypond-devel mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: Improving the Contributors Guide and LilyDev

Federico Bruni
2015-05-06 7:19 GMT+02:00 Janek Warchoł <[hidden email]>:

> as I've already mentioned, I've already started working on a new
> LilyDev.  I'm going to use tools that should make it easy to build
> different versions of LilyDev (e.g. 32-bit and 64-bit, possibly also
> based on different distros).
>
>
I though that you had some ideas on how to improve LilyDev, not that you
were working on building a new LilyDev..


> In order to reduce work duplication, I suggest to wait with further
> discussion until I have a working "prototype", which I'll present to
> you for evaluation.  Hopefully this will happen within a week from
> now.
>

I started updating LilyDev yesterday but spent just 20 minutes.
I invested some time last year to get started, but live-build is quite easy
to update and maintain.

I'll wait for your prototype, even if it looks like a work duplication
already.
Why not improving what's already available? Which advantages have the tools
you are using?
_______________________________________________
lilypond-devel mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-devel
12