Tutorials

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

Tutorials

Alexandre Devaux
Hi folks,

Victor and I wrote a draft for tutorials (some of it is obsolete), in the readme here:
https://github.com/iTowns/itowns2/tree/README

I think ideally we should have a tutorials page which list all tutorials which will have their own page.

Something like:
itowns-project.org/tutorials.html
  itowns-project.org/tutorials/basicstartup.html
  itowns-project.org/tutorials/addGeometryTutorial.html
  ...

Currently the website is on https://github.com/iTowns/itowns.github.io, we could store images of examples there.

If you have other ideas on that topic don't hesitate!

Feel free to contribute on https://github.com/iTowns/itowns2/tree/README 


Alexandre

________________________________________
De : iTowns-dev [[hidden email]] de la part de [hidden email] [[hidden email]]
Date d'envoi : jeudi 29 juin 2017 15:20
À : [hidden email]
Objet : iTowns-dev Digest, Vol 13, Issue 6

Send iTowns-dev mailing list submissions to
        [hidden email]

To subscribe or unsubscribe via the World Wide Web, visit
        https://lists.osgeo.org/mailman/listinfo/itowns-dev
or, via email, send a message with subject or body 'help' to
        [hidden email]

You can reach the person managing the list at
        [hidden email]

When replying, please edit your Subject line so it is more specific
than "Re: Contents of iTowns-dev digest..."


Today's Topics:

   1. Re: Video in repo (Thomas Broyer)
   2.  Release: name and version? (Alexandre Devaux)
   3. Re: Release: name and version? (Augustin Trancart)


----------------------------------------------------------------------

Message: 1
Date: Thu, 29 Jun 2017 14:26:50 +0200
From: Thomas Broyer <[hidden email]>
To: [hidden email]
Cc: "[hidden email]" <[hidden email]>
Subject: Re: [iTowns-dev] Video in repo
Message-ID:
        <CA+9O_-RNszRYn_p+A0jDm5QrTHRYD7oHdbX=[hidden email]>
Content-Type: text/plain; charset="utf-8"

2017-06-29 13:51 GMT+02:00 Augustin Trancart <[hidden email]
>:

> I basically trust maintainer not to merge big files,


Oh, you mean like for that video file? :troll:


> but yes, if we can automate it, it's even better.


Note that apparently aabc913 didn't went through a pull request, so we
couldn't have prevented it anyway (Travis could have failed, and then a
push-force would have been needed anyway)

Cordialement,
--
Thomas Broyer
Atol Conseils et Développements
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/itowns-dev/attachments/20170629/c6cec9ae/attachment-0001.html>

------------------------------

Message: 2
Date: Thu, 29 Jun 2017 13:13:21 +0000
From: Alexandre Devaux <[hidden email]>
To: "[hidden email]" <[hidden email]>
Subject: [iTowns-dev]  Release: name and version?
Message-ID: <[hidden email]>
Content-Type: text/plain; charset="Windows-1252"

Hi,

I would go for 1) too. "rename itowns repo into itowns-old (for instance), and we rename itowns2 into itowns"




--
Alexandre Devaux
Chargé d'Etudes et de Recherche
Laboratoire MATIS, IGN
Tel: 01 43 98 85 73

________________________________________
De : iTowns-dev [[hidden email]] de la part de [hidden email] [[hidden email]]
Date d'envoi : jeudi 29 juin 2017 13:51
À : [hidden email]
Objet : iTowns-dev Digest, Vol 13, Issue 5

Send iTowns-dev mailing list submissions to
        [hidden email]

To subscribe or unsubscribe via the World Wide Web, visit
        https://lists.osgeo.org/mailman/listinfo/itowns-dev
or, via email, send a message with subject or body 'help' to
        [hidden email]

You can reach the person managing the list at
        [hidden email]

When replying, please edit your Subject line so it is more specific
than "Re: Contents of iTowns-dev digest..."


Today's Topics:

   1. Re: Video in repo (Augustin Trancart)
   2. Re: Video in repo (Thomas Broyer)
   3. Re: Release: name and version? (Vincent Picavet (ml))
   4. Re: Video in repo (Vincent Picavet (ml))
   5. Re: Video in repo (Augustin Trancart)


----------------------------------------------------------------------

Message: 1
Date: Thu, 29 Jun 2017 12:13:06 +0200
From: Augustin Trancart <[hidden email]>
To: Thomas Broyer <[hidden email]>
Cc: "[hidden email]" <[hidden email]>
Subject: Re: [iTowns-dev] Video in repo
Message-ID: <[hidden email]>
Content-Type: text/plain; charset="utf-8"

Yes, agree with the idea of removing other big obsolete files as well.

I'm not too worried about pull/pushes. If we require the files to be removed
before merge, these commits would become unreachable after the force-push, and
would eventually be garbage collected (providing we are careful at removing old
branches).

Augustin Trancart - Oslandia
[hidden email]

On 29/06/2017 12:03, Thomas Broyer wrote:

> 15 months ago (or so), big files were added to the project and then removed, and
> I also floated the idea of a history rewrite. I never got the "go" so it hasn't
> been done. Iff we go that road for the video file, I suggest we also get rid of
> those old commits.
>
> I don't have a strong opinion whether this should be done, but it's clear that
> it's now or never.
>
> I'd suggest we eventually find a way to somehow reject pull requests (we
> apparently can't reject commits/pushes) with big files (or many smaller files!);
> possibly an additional check in Travis, I don't know.
>
> 2017-06-29 11:32 GMT+02:00 Augustin Trancart <[hidden email]
> <mailto:[hidden email]>>:
>
>     Hi there!
>
>     Quick question with the release in sight: a video of 24M has been added (in
>     aabc913) and removed later (in b321c01) in the repository. This makes the clone
>     of the repository quite long even though the video is not in master any more.
>     Should we rewrite the history to get rid of it?
>
>     It's possible, but it implies a force-push on master. It means that everybody
>     will need to use "git rebase --onto master <commit-range>" for all their
>     branches after this push is done and force-push them (and maybe a git reset
>     --hard on their local master, I'm not sure how clever git is nowadays).
>
>     It's a low risk process (we'll keep a copy of the old master around), but it's a
>     bit of a hassle and requires synchronization between us. I believe it is
>     possible, but if we want to do it, we'd better do it now, before success hits us
>     hard and we have thousands of contributors (yeah, I'm an optimistic kind of guy
>     ;-) )
>
>     Thoughts?
>
>     --
>     Augustin Trancart - Oslandia
>     [hidden email] <mailto:[hidden email]>
>
>
>     _______________________________________________
>     iTowns-dev mailing list
>     [hidden email] <mailto:[hidden email]>
>     https://lists.osgeo.org/mailman/listinfo/itowns-dev
>     <https://lists.osgeo.org/mailman/listinfo/itowns-dev>
>
>
>
>
> --
>
> Cordialement,
> --
> Thomas Broyer
> Atol Conseils et Développements
>

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: OpenPGP digital signature
URL: <http://lists.osgeo.org/pipermail/itowns-dev/attachments/20170629/674fd290/attachment-0001.sig>

------------------------------

Message: 2
Date: Thu, 29 Jun 2017 12:34:13 +0200
From: Thomas Broyer <[hidden email]>
To: [hidden email]
Cc: "[hidden email]" <[hidden email]>
Subject: Re: [iTowns-dev] Video in repo
Message-ID:
        <[hidden email]>
Content-Type: text/plain; charset="utf-8"

2017-06-29 12:13 GMT+02:00 Augustin Trancart <[hidden email]
>:

> Yes, agree with the idea of removing other big obsolete files as well.
>
> I'm not too worried about pull/pushes. If we require the files to be
> removed
> before merge, these commits would become unreachable after the force-push,
> and
> would eventually be garbage collected (providing we are careful at
> removing old
> branches).


Not sure I understand that last paragraph.
My remark wrt rejecting pull requests (or pushes) with big files was to
prevent this situation from happening again (in other words, as you said,
"require the files to be removed before merge", but automate it).

Note also that GitHub will keep the files anyway in their special
refs/pull/ references [1], you'll just never sync them (unless you want it)
because (by default) Git only syncs refs/heads/ and refs/tags/
[1] https://help.github.com/articles/checking-out-pull-requests-locally/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/itowns-dev/attachments/20170629/74f11c2d/attachment-0001.html>

------------------------------

Message: 3
Date: Thu, 29 Jun 2017 12:58:19 +0200
From: "Vincent Picavet (ml)" <[hidden email]>
To: Thomas Broyer <[hidden email]>,
        [hidden email]
Cc: "[hidden email]" <[hidden email]>
Subject: Re: [iTowns-dev] Release: name and version?
Message-ID: <[hidden email]>
Content-Type: text/plain; charset=utf-8

Hi,

On 29/06/2017 12:14, Thomas Broyer wrote:
> FWIW, my vote would go to 1/ (particularly if we *also* rewrite the Git
> history)
> Rename itowns/itowns to itowns/itowns1 and itowns/itowns2 to
> itowns/itowns, add a note to the README that iTowns 1 can be found at
> itowns/itowns1, and release a v2 (if it makes no guarantee about API
> stability, then label it as alpha or beta, or release candidate
> depending on the [lack of] confidence in API [in]stability).
>
> Either that or finding a new name…

Agree with this. Renaming itowns to itowns1 or itowns-legacy seems best
to avoid confusion, and keep itowns name for current version.

As for the name change, it could be an option, but a lot of
communication has been made around itowns already, especially at IGN, so
I think it would be difficult.

Vincent


>
> 2017-06-29 11:42 GMT+02:00 Augustin Trancart
> <[hidden email] <mailto:[hidden email]>>:
>
>     Hi there!
>
>     Our first release approaching, I have some questions about it about
>     the package
>     name and its version.
>
>     The current situation: our repo is currently called itowns2. We have
>     the old
>     repo called itowns. The npm package (a 0.0.0-alpha published for testing
>     purpose) is currently called itowns[1]. I see several possibilities:
>
>     1/ we stick with the "itowns" name. We rename itowns repo into
>     itowns-old (for
>     instance), and we rename itowns2 into itowns. We release v2.0.0 on
>     5th of July
>     (imho we can't release another number to avoid confusion with itowns1)
>
>     2/ we stick with the current situation: "itowns" for the npm package
>     only, and
>     "itowns2" for the repo. After all, the repo is linked in the npm
>     package page.
>     We release a v2.0.0 for the same reason as 1/
>
>     3/ We keep the name itowns2 for this release everywhere. Therefore,
>     we keep the
>     github repo as it is and we create a new npm package named itowns2
>     (and delete
>     package itowns, because it is really itowns2 inside). We can release
>     whatever
>     version number we want.
>
>     4/ another combination of the above/solution?
>
>
>     I don't really like current situation (aka 2/), because I think it's
>     the most
>     confusing setup (different name for the package and the repo, and an
>     old itowns
>     repo with same name as package name still in existence).
>
>     1/ has the advantage of reducing the confusion between itowns and
>     itowns2
>     (because there would be only itowns) and be clear about which one is
>     the current
>     one, but it forces us to rename some repos (never ideal) and release
>     a v2
>     (instead of a v0 or v1 for instance).
>
>     3/ has the advantage of being the least disruptive and the more
>     respectful of
>     the history of the project. If we choose this solution, we must be
>     clear in
>     itowns old repo that new development should be done in itowns2 repo.
>     If we
>     choose this, I would advocate to release a v0.something, because in
>     semver[2],
>     0.x.x versions do not need to have a stable API. Then we can release
>     a v1 some
>     weeks/months before the geoportail itowns release. It's my preferred
>     choice.
>
>
>     For a more general thought about version numbers, I would like to follow
>     semantic versioning[2]. I think it's a great way to convey
>     incompatible change
>     informations to our users. For this a prerequisite would be to
>     define our Public
>     API. I propose a simple criterion : everything that's currently
>     documented in
>     our jsdoc page is our current API. Everything else is not, and we
>     make it clear so.
>
>     What do you think about all that?
>
>     [1] https://www.npmjs.com/package/itowns
>     <https://www.npmjs.com/package/itowns>
>     [2] http://semver.org/
>     --
>     Augustin Trancart - Oslandia
>     [hidden email] <mailto:[hidden email]>
>
>     PS: We can examine crazier ideas too, like another name entirely? eg
>     Barium
>     (Cesium is elem n°55, Barium is 56, so Cesium++ ;-) )?
>
>
>     _______________________________________________
>     iTowns-dev mailing list
>     [hidden email] <mailto:[hidden email]>
>     https://lists.osgeo.org/mailman/listinfo/itowns-dev
>     <https://lists.osgeo.org/mailman/listinfo/itowns-dev>
>
>
>
>
> --
>
> Cordialement,
> --
> Thomas Broyer
> Atol Conseils et Développements
>
>
>
> _______________________________________________
> iTowns-dev mailing list
> [hidden email]
> https://lists.osgeo.org/mailman/listinfo/itowns-dev
>



------------------------------

Message: 4
Date: Thu, 29 Jun 2017 13:00:55 +0200
From: "Vincent Picavet (ml)" <[hidden email]>
To: Pierre-Eric Pelloux-Prayer
        <[hidden email]>, [hidden email]
Subject: Re: [iTowns-dev] Video in repo
Message-ID: <[hidden email]>
Content-Type: text/plain; charset=utf-8

Hello,

+1 also on history rewrite.
Try to gather all big files, not just the video.
Doing this just before the release would probably minimize the number of
branches concerned by this change ( aka : "merge now or expect trouble"
;-) .

Vincent

On 29/06/2017 11:53, Pierre-Eric Pelloux-Prayer wrote:

> +1 let's do this before the first release.
>
>
> Le 29/06/2017 à 11:32, Augustin Trancart a écrit :
>> Hi there!
>>
>> Quick question with the release in sight: a video of 24M has been added (in
>> aabc913) and removed later (in b321c01) in the repository. This makes the clone
>> of the repository quite long even though the video is not in master any more.
>> Should we rewrite the history to get rid of it?
>>
>> It's possible, but it implies a force-push on master. It means that everybody
>> will need to use "git rebase --onto master <commit-range>" for all their
>> branches after this push is done and force-push them (and maybe a git reset
>> --hard on their local master, I'm not sure how clever git is nowadays).
>>
>> It's a low risk process (we'll keep a copy of the old master around), but it's a
>> bit of a hassle and requires synchronization between us. I believe it is
>> possible, but if we want to do it, we'd better do it now, before success hits us
>> hard and we have thousands of contributors (yeah, I'm an optimistic kind of guy
>> ;-) )
>>
>> Thoughts?
>>
>>
>>
>> _______________________________________________
>> iTowns-dev mailing list
>> [hidden email]
>> https://lists.osgeo.org/mailman/listinfo/itowns-dev
>>
> _______________________________________________
> iTowns-dev mailing list
> [hidden email]
> https://lists.osgeo.org/mailman/listinfo/itowns-dev
>



------------------------------

Message: 5
Date: Thu, 29 Jun 2017 13:51:40 +0200
From: Augustin Trancart <[hidden email]>
To: Thomas Broyer <[hidden email]>
Cc: "[hidden email]" <[hidden email]>
Subject: Re: [iTowns-dev] Video in repo
Message-ID: <[hidden email]>
Content-Type: text/plain; charset="utf-8"

I basically trust maintainer not to merge big files, but yes, if we can automate
it, it's even better.

Augustin Trancart - Oslandia
[hidden email]

On 29/06/2017 12:34, Thomas Broyer wrote:

>
>
> 2017-06-29 12:13 GMT+02:00 Augustin Trancart <[hidden email]
> <mailto:[hidden email]>>:
>
>     Yes, agree with the idea of removing other big obsolete files as well.
>
>     I'm not too worried about pull/pushes. If we require the files to be removed
>     before merge, these commits would become unreachable after the force-push, and
>     would eventually be garbage collected (providing we are careful at removing old
>     branches).
>
>
> Not sure I understand that last paragraph.
> My remark wrt rejecting pull requests (or pushes) with big files was to prevent
> this situation from happening again (in other words, as you said, "require the
> files to be removed before merge", but automate it).
>
> Note also that GitHub will keep the files anyway in their special refs/pull/
> references [1], you'll just never sync them (unless you want it) because (by
> default) Git only syncs refs/heads/ and refs/tags/
> [1] https://help.github.com/articles/checking-out-pull-requests-locally/

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: OpenPGP digital signature
URL: <http://lists.osgeo.org/pipermail/itowns-dev/attachments/20170629/02a1cc9b/attachment.sig>

------------------------------

Subject: Digest Footer

_______________________________________________
iTowns-dev mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/itowns-dev


------------------------------

End of iTowns-dev Digest, Vol 13, Issue 5
*****************************************


------------------------------

Message: 3
Date: Thu, 29 Jun 2017 15:20:11 +0200
From: Augustin Trancart <[hidden email]>
To: [hidden email]
Subject: Re: [iTowns-dev] Release: name and version?
Message-ID: <[hidden email]>
Content-Type: text/plain; charset="utf-8"

Ok, at the moment it seems there is a consensus for going with 1/.

I propose to do the dull work of renaming repos on the 4th of July, if no
objection until then (or everything including the release on the 5th).

so itowns -> itowns-legacy (+ a link in the README)
   itowns2 -> itowns

I guess the released version number would be v2? Or something else?

Augustin Trancart - Oslandia
[hidden email]

On 29/06/2017 15:13, Alexandre Devaux wrote:

> Hi,
>
> I would go for 1) too. "rename itowns repo into itowns-old (for instance), and we rename itowns2 into itowns"
>
>
>
>
> --
> Alexandre Devaux
> Chargé d'Etudes et de Recherche
> Laboratoire MATIS, IGN
> Tel: 01 43 98 85 73
>
> ________________________________________
> De : iTowns-dev [[hidden email]] de la part de [hidden email] [[hidden email]]
> Date d'envoi : jeudi 29 juin 2017 13:51
> À : [hidden email]
> Objet : iTowns-dev Digest, Vol 13, Issue 5
>
> Send iTowns-dev mailing list submissions to
>         [hidden email]
>
> To subscribe or unsubscribe via the World Wide Web, visit
>         https://lists.osgeo.org/mailman/listinfo/itowns-dev
> or, via email, send a message with subject or body 'help' to
>         [hidden email]
>
> You can reach the person managing the list at
>         [hidden email]
>
> When replying, please edit your Subject line so it is more specific
> than "Re: Contents of iTowns-dev digest..."
>
>
> Today's Topics:
>
>    1. Re: Video in repo (Augustin Trancart)
>    2. Re: Video in repo (Thomas Broyer)
>    3. Re: Release: name and version? (Vincent Picavet (ml))
>    4. Re: Video in repo (Vincent Picavet (ml))
>    5. Re: Video in repo (Augustin Trancart)
>
>
> ----------------------------------------------------------------------
>
> Message: 1
> Date: Thu, 29 Jun 2017 12:13:06 +0200
> From: Augustin Trancart <[hidden email]>
> To: Thomas Broyer <[hidden email]>
> Cc: "[hidden email]" <[hidden email]>
> Subject: Re: [iTowns-dev] Video in repo
> Message-ID: <[hidden email]>
> Content-Type: text/plain; charset="utf-8"
>
> Yes, agree with the idea of removing other big obsolete files as well.
>
> I'm not too worried about pull/pushes. If we require the files to be removed
> before merge, these commits would become unreachable after the force-push, and
> would eventually be garbage collected (providing we are careful at removing old
> branches).
>
> Augustin Trancart - Oslandia
> [hidden email]
>
> On 29/06/2017 12:03, Thomas Broyer wrote:
>> 15 months ago (or so), big files were added to the project and then removed, and
>> I also floated the idea of a history rewrite. I never got the "go" so it hasn't
>> been done. Iff we go that road for the video file, I suggest we also get rid of
>> those old commits.
>>
>> I don't have a strong opinion whether this should be done, but it's clear that
>> it's now or never.
>>
>> I'd suggest we eventually find a way to somehow reject pull requests (we
>> apparently can't reject commits/pushes) with big files (or many smaller files!);
>> possibly an additional check in Travis, I don't know.
>>
>> 2017-06-29 11:32 GMT+02:00 Augustin Trancart <[hidden email]
>> <mailto:[hidden email]>>:
>>
>>     Hi there!
>>
>>     Quick question with the release in sight: a video of 24M has been added (in
>>     aabc913) and removed later (in b321c01) in the repository. This makes the clone
>>     of the repository quite long even though the video is not in master any more.
>>     Should we rewrite the history to get rid of it?
>>
>>     It's possible, but it implies a force-push on master. It means that everybody
>>     will need to use "git rebase --onto master <commit-range>" for all their
>>     branches after this push is done and force-push them (and maybe a git reset
>>     --hard on their local master, I'm not sure how clever git is nowadays).
>>
>>     It's a low risk process (we'll keep a copy of the old master around), but it's a
>>     bit of a hassle and requires synchronization between us. I believe it is
>>     possible, but if we want to do it, we'd better do it now, before success hits us
>>     hard and we have thousands of contributors (yeah, I'm an optimistic kind of guy
>>     ;-) )
>>
>>     Thoughts?
>>
>>     --
>>     Augustin Trancart - Oslandia
>>     [hidden email] <mailto:[hidden email]>
>>
>>
>>     _______________________________________________
>>     iTowns-dev mailing list
>>     [hidden email] <mailto:[hidden email]>
>>     https://lists.osgeo.org/mailman/listinfo/itowns-dev
>>     <https://lists.osgeo.org/mailman/listinfo/itowns-dev>
>>
>>
>>
>>
>> --
>>
>> Cordialement,
>> --
>> Thomas Broyer
>> Atol Conseils et Développements
>>
>
> -------------- next part --------------
> A non-text attachment was scrubbed...
> Name: signature.asc
> Type: application/pgp-signature
> Size: 819 bytes
> Desc: OpenPGP digital signature
> URL: <http://lists.osgeo.org/pipermail/itowns-dev/attachments/20170629/674fd290/attachment-0001.sig>
>
> ------------------------------
>
> Message: 2
> Date: Thu, 29 Jun 2017 12:34:13 +0200
> From: Thomas Broyer <[hidden email]>
> To: [hidden email]
> Cc: "[hidden email]" <[hidden email]>
> Subject: Re: [iTowns-dev] Video in repo
> Message-ID:
>         <[hidden email]>
> Content-Type: text/plain; charset="utf-8"
>
> 2017-06-29 12:13 GMT+02:00 Augustin Trancart <[hidden email]
>> :
>
>> Yes, agree with the idea of removing other big obsolete files as well.
>>
>> I'm not too worried about pull/pushes. If we require the files to be
>> removed
>> before merge, these commits would become unreachable after the force-push,
>> and
>> would eventually be garbage collected (providing we are careful at
>> removing old
>> branches).
>
>
> Not sure I understand that last paragraph.
> My remark wrt rejecting pull requests (or pushes) with big files was to
> prevent this situation from happening again (in other words, as you said,
> "require the files to be removed before merge", but automate it).
>
> Note also that GitHub will keep the files anyway in their special
> refs/pull/ references [1], you'll just never sync them (unless you want it)
> because (by default) Git only syncs refs/heads/ and refs/tags/
> [1] https://help.github.com/articles/checking-out-pull-requests-locally/
> -------------- next part --------------
> An HTML attachment was scrubbed...
> URL: <http://lists.osgeo.org/pipermail/itowns-dev/attachments/20170629/74f11c2d/attachment-0001.html>
>
> ------------------------------
>
> Message: 3
> Date: Thu, 29 Jun 2017 12:58:19 +0200
> From: "Vincent Picavet (ml)" <[hidden email]>
> To: Thomas Broyer <[hidden email]>,
>         [hidden email]
> Cc: "[hidden email]" <[hidden email]>
> Subject: Re: [iTowns-dev] Release: name and version?
> Message-ID: <[hidden email]>
> Content-Type: text/plain; charset=utf-8
>
> Hi,
>
> On 29/06/2017 12:14, Thomas Broyer wrote:
>> FWIW, my vote would go to 1/ (particularly if we *also* rewrite the Git
>> history)
>> Rename itowns/itowns to itowns/itowns1 and itowns/itowns2 to
>> itowns/itowns, add a note to the README that iTowns 1 can be found at
>> itowns/itowns1, and release a v2 (if it makes no guarantee about API
>> stability, then label it as alpha or beta, or release candidate
>> depending on the [lack of] confidence in API [in]stability).
>>
>> Either that or finding a new name…
>
> Agree with this. Renaming itowns to itowns1 or itowns-legacy seems best
> to avoid confusion, and keep itowns name for current version.
>
> As for the name change, it could be an option, but a lot of
> communication has been made around itowns already, especially at IGN, so
> I think it would be difficult.
>
> Vincent
>
>
>>
>> 2017-06-29 11:42 GMT+02:00 Augustin Trancart
>> <[hidden email] <mailto:[hidden email]>>:
>>
>>     Hi there!
>>
>>     Our first release approaching, I have some questions about it about
>>     the package
>>     name and its version.
>>
>>     The current situation: our repo is currently called itowns2. We have
>>     the old
>>     repo called itowns. The npm package (a 0.0.0-alpha published for testing
>>     purpose) is currently called itowns[1]. I see several possibilities:
>>
>>     1/ we stick with the "itowns" name. We rename itowns repo into
>>     itowns-old (for
>>     instance), and we rename itowns2 into itowns. We release v2.0.0 on
>>     5th of July
>>     (imho we can't release another number to avoid confusion with itowns1)
>>
>>     2/ we stick with the current situation: "itowns" for the npm package
>>     only, and
>>     "itowns2" for the repo. After all, the repo is linked in the npm
>>     package page.
>>     We release a v2.0.0 for the same reason as 1/
>>
>>     3/ We keep the name itowns2 for this release everywhere. Therefore,
>>     we keep the
>>     github repo as it is and we create a new npm package named itowns2
>>     (and delete
>>     package itowns, because it is really itowns2 inside). We can release
>>     whatever
>>     version number we want.
>>
>>     4/ another combination of the above/solution?
>>
>>
>>     I don't really like current situation (aka 2/), because I think it's
>>     the most
>>     confusing setup (different name for the package and the repo, and an
>>     old itowns
>>     repo with same name as package name still in existence).
>>
>>     1/ has the advantage of reducing the confusion between itowns and
>>     itowns2
>>     (because there would be only itowns) and be clear about which one is
>>     the current
>>     one, but it forces us to rename some repos (never ideal) and release
>>     a v2
>>     (instead of a v0 or v1 for instance).
>>
>>     3/ has the advantage of being the least disruptive and the more
>>     respectful of
>>     the history of the project. If we choose this solution, we must be
>>     clear in
>>     itowns old repo that new development should be done in itowns2 repo.
>>     If we
>>     choose this, I would advocate to release a v0.something, because in
>>     semver[2],
>>     0.x.x versions do not need to have a stable API. Then we can release
>>     a v1 some
>>     weeks/months before the geoportail itowns release. It's my preferred
>>     choice.
>>
>>
>>     For a more general thought about version numbers, I would like to follow
>>     semantic versioning[2]. I think it's a great way to convey
>>     incompatible change
>>     informations to our users. For this a prerequisite would be to
>>     define our Public
>>     API. I propose a simple criterion : everything that's currently
>>     documented in
>>     our jsdoc page is our current API. Everything else is not, and we
>>     make it clear so.
>>
>>     What do you think about all that?
>>
>>     [1] https://www.npmjs.com/package/itowns
>>     <https://www.npmjs.com/package/itowns>
>>     [2] http://semver.org/
>>     --
>>     Augustin Trancart - Oslandia
>>     [hidden email] <mailto:[hidden email]>
>>
>>     PS: We can examine crazier ideas too, like another name entirely? eg
>>     Barium
>>     (Cesium is elem n°55, Barium is 56, so Cesium++ ;-) )?
>>
>>
>>     _______________________________________________
>>     iTowns-dev mailing list
>>     [hidden email] <mailto:[hidden email]>
>>     https://lists.osgeo.org/mailman/listinfo/itowns-dev
>>     <https://lists.osgeo.org/mailman/listinfo/itowns-dev>
>>
>>
>>
>>
>> --
>>
>> Cordialement,
>> --
>> Thomas Broyer
>> Atol Conseils et Développements
>>
>>
>>
>> _______________________________________________
>> iTowns-dev mailing list
>> [hidden email]
>> https://lists.osgeo.org/mailman/listinfo/itowns-dev
>>
>
>
>
> ------------------------------
>
> Message: 4
> Date: Thu, 29 Jun 2017 13:00:55 +0200
> From: "Vincent Picavet (ml)" <[hidden email]>
> To: Pierre-Eric Pelloux-Prayer
>         <[hidden email]>, [hidden email]
> Subject: Re: [iTowns-dev] Video in repo
> Message-ID: <[hidden email]>
> Content-Type: text/plain; charset=utf-8
>
> Hello,
>
> +1 also on history rewrite.
> Try to gather all big files, not just the video.
> Doing this just before the release would probably minimize the number of
> branches concerned by this change ( aka : "merge now or expect trouble"
> ;-) .
>
> Vincent
>
> On 29/06/2017 11:53, Pierre-Eric Pelloux-Prayer wrote:
>> +1 let's do this before the first release.
>>
>>
>> Le 29/06/2017 à 11:32, Augustin Trancart a écrit :
>>> Hi there!
>>>
>>> Quick question with the release in sight: a video of 24M has been added (in
>>> aabc913) and removed later (in b321c01) in the repository. This makes the clone
>>> of the repository quite long even though the video is not in master any more.
>>> Should we rewrite the history to get rid of it?
>>>
>>> It's possible, but it implies a force-push on master. It means that everybody
>>> will need to use "git rebase --onto master <commit-range>" for all their
>>> branches after this push is done and force-push them (and maybe a git reset
>>> --hard on their local master, I'm not sure how clever git is nowadays).
>>>
>>> It's a low risk process (we'll keep a copy of the old master around), but it's a
>>> bit of a hassle and requires synchronization between us. I believe it is
>>> possible, but if we want to do it, we'd better do it now, before success hits us
>>> hard and we have thousands of contributors (yeah, I'm an optimistic kind of guy
>>> ;-) )
>>>
>>> Thoughts?
>>>
>>>
>>>
>>> _______________________________________________
>>> iTowns-dev mailing list
>>> [hidden email]
>>> https://lists.osgeo.org/mailman/listinfo/itowns-dev
>>>
>> _______________________________________________
>> iTowns-dev mailing list
>> [hidden email]
>> https://lists.osgeo.org/mailman/listinfo/itowns-dev
>>
>
>
>
> ------------------------------
>
> Message: 5
> Date: Thu, 29 Jun 2017 13:51:40 +0200
> From: Augustin Trancart <[hidden email]>
> To: Thomas Broyer <[hidden email]>
> Cc: "[hidden email]" <[hidden email]>
> Subject: Re: [iTowns-dev] Video in repo
> Message-ID: <[hidden email]>
> Content-Type: text/plain; charset="utf-8"
>
> I basically trust maintainer not to merge big files, but yes, if we can automate
> it, it's even better.
>
> Augustin Trancart - Oslandia
> [hidden email]
>
> On 29/06/2017 12:34, Thomas Broyer wrote:
>>
>>
>> 2017-06-29 12:13 GMT+02:00 Augustin Trancart <[hidden email]
>> <mailto:[hidden email]>>:
>>
>>     Yes, agree with the idea of removing other big obsolete files as well.
>>
>>     I'm not too worried about pull/pushes. If we require the files to be removed
>>     before merge, these commits would become unreachable after the force-push, and
>>     would eventually be garbage collected (providing we are careful at removing old
>>     branches).
>>
>>
>> Not sure I understand that last paragraph.
>> My remark wrt rejecting pull requests (or pushes) with big files was to prevent
>> this situation from happening again (in other words, as you said, "require the
>> files to be removed before merge", but automate it).
>>
>> Note also that GitHub will keep the files anyway in their special refs/pull/
>> references [1], you'll just never sync them (unless you want it) because (by
>> default) Git only syncs refs/heads/ and refs/tags/
>> [1] https://help.github.com/articles/checking-out-pull-requests-locally/
>
> -------------- next part --------------
> A non-text attachment was scrubbed...
> Name: signature.asc
> Type: application/pgp-signature
> Size: 819 bytes
> Desc: OpenPGP digital signature
> URL: <http://lists.osgeo.org/pipermail/itowns-dev/attachments/20170629/02a1cc9b/attachment.sig>
>
> ------------------------------
>
> Subject: Digest Footer
>
> _______________________________________________
> iTowns-dev mailing list
> [hidden email]
> https://lists.osgeo.org/mailman/listinfo/itowns-dev
>
>
> ------------------------------
>
> End of iTowns-dev Digest, Vol 13, Issue 5
> *****************************************
> _______________________________________________
> iTowns-dev mailing list
> [hidden email]
> https://lists.osgeo.org/mailman/listinfo/itowns-dev
>

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: OpenPGP digital signature
URL: <http://lists.osgeo.org/pipermail/itowns-dev/attachments/20170629/00b7f3e0/attachment.sig>

------------------------------

Subject: Digest Footer

_______________________________________________
iTowns-dev mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/itowns-dev


------------------------------

End of iTowns-dev Digest, Vol 13, Issue 6
*****************************************
_______________________________________________
iTowns-dev mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/itowns-dev
Reply | Threaded
Open this post in threaded view
|

Re: Tutorials

Pierre-Eric Pelloux-Prayer
Hi,

>
> Victor and I wrote a draft for tutorials (some of it is obsolete), in the readme here:
> https://github.com/iTowns/itowns2/tree/README

Good idea, and thanks for working on the documentation topic.


>
> I think ideally we should have a tutorials page which list all tutorials which will have their own page.
>
> Something like:
> itowns-project.org/tutorials.html
>   itowns-project.org/tutorials/basicstartup.html
>   itowns-project.org/tutorials/addGeometryTutorial.html
>   ...
>

I really like the three.js/docs layout.
On the same page you get access to: tutorials/introduction articles, API documentation and examples.

One big + is that you can just type something in the search bar (eg: Material) and you get to discover
everything available on the subject.


> If you have other ideas on that topic don't hesitate!

Here are 3 independant ideas:

1. for examples/tutorials, I think litterate programming offers a nice solution.

A big part of https://github.com/iTowns/itowns2/blob/README/README.md is a copy paste of index.html.
I see at least 2 benefits to write the same content direclty in index.html:
  - index.html would become documented :)
  - the comments would be easier to keep synchronized with itowns changes (it's too easy to forget to
    update the README.md or addGeometry.md)

2. consistent documentation style for examples and API

See issue https://github.com/iTowns/itowns2/issues/314 (discussing jsdoc, docco and other tools for API doc)

Also it could make sense to use a single tool to build our website (instead of jekyll + API doc tool + examples/tutorial
doc tool).
Here's what I imagined: docco for API/examples doc and a static landing page showing the README.md + screenshots of
itowns app (like https://threejs.org/).

3. I believe that, as iTowns' users will also be three.js users,  it makes sense to try to match the style and
organization of three.js website.
I guess that all the discussed tools have configurable layout/template, so it shouldn't be too hard to achieve.


Regards,
Pierre-Eric

_______________________________________________
iTowns-dev mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/itowns-dev
Reply | Threaded
Open this post in threaded view
|

Re: Tutorials

Augustin Trancart
In reply to this post by Alexandre Devaux
Hi !

Great for the README, I'll try to comment on it today.


On 29/06/2017 19:29, Alexandre Devaux wrote:

> Hi folks,
>
> Victor and I wrote a draft for tutorials (some of it is obsolete), in the readme here:
> https://github.com/iTowns/itowns2/tree/README
>
> I think ideally we should have a tutorials page which list all tutorials which will have their own page.
>
> Something like:
> itowns-project.org/tutorials.html
>   itowns-project.org/tutorials/basicstartup.html
>   itowns-project.org/tutorials/addGeometryTutorial.html
>   ...
Yep, but AFAIK we don't have tutorials yet, right? As the release is next week,
we might not have time to write those. Let's add a tutorial section when the
first one is written.

>
> Currently the website is on https://github.com/iTowns/itowns.github.io, we could store images of examples there.

Let's be more ambitious and store real, working examples in the landing page!
After all itowns is web-based, images are so 1990 ;-) One implication of this:
we should detect if the user is on an unsupported browser, and either display a
warning or display a screenshot instead (or both)? Or we don't care, considering
that most of our visitors would be from supported browsers?

I can start to work on the website and make a PR when I have the first pass
ready, WDYT?

>
> If you have other ideas on that topic don't hesitate!
>
> Feel free to contribute on https://github.com/iTowns/itowns2/tree/README 

Thanks!

>
> Alexandre

I carry on:

On 30/06/2017 09:11, Pierre-Eric Pelloux-Prayer wrote:
>>
>> I think ideally we should have a tutorials page which list all tutorials
which will have their own page.

>>
>> Something like:
>> itowns-project.org/tutorials.html
>>   itowns-project.org/tutorials/basicstartup.html
>>   itowns-project.org/tutorials/addGeometryTutorial.html
>>   ...
>>
>
> I really like the three.js/docs layout.
> On the same page you get access to: tutorials/introduction articles, API
documentation and examples.

Agreed.

>
> One big + is that you can just type something in the search bar (eg: Material)
and you get to discover
> everything available on the subject.

We *need* that. I'll work on this.

>
>> If you have other ideas on that topic don't hesitate!
>
> Here are 3 independant ideas:
>
> 1. for examples/tutorials, I think litterate programming offers a nice solution.

That's clearly a big plus on docco for the examples.

>
> 2. consistent documentation style for examples and API
>
> See issue https://github.com/iTowns/itowns2/issues/314 (discussing jsdoc,
docco and other tools for API doc)
>
> Also it could make sense to use a single tool to build our website (instead of
jekyll + API doc tool + examples/tutorial
> doc tool).

Not necessarily... I don't know: it might cause more pain that it solves. It
depends what we want in the website (do we want individual pages that are
neither api doc nor examples?)


>
>
> Regards,
> Pierre-Eric

Same ;-)

Augustin Trancart - Oslandia





>
> ________________________________________
> De : iTowns-dev [[hidden email]] de la part de [hidden email] [[hidden email]]
> Date d'envoi : jeudi 29 juin 2017 15:20
> À : [hidden email]
> Objet : iTowns-dev Digest, Vol 13, Issue 6
>
> Send iTowns-dev mailing list submissions to
>         [hidden email]
>
> To subscribe or unsubscribe via the World Wide Web, visit
>         https://lists.osgeo.org/mailman/listinfo/itowns-dev
> or, via email, send a message with subject or body 'help' to
>         [hidden email]
>
> You can reach the person managing the list at
>         [hidden email]
>
> When replying, please edit your Subject line so it is more specific
> than "Re: Contents of iTowns-dev digest..."
>
>
> Today's Topics:
>
>    1. Re: Video in repo (Thomas Broyer)
>    2.  Release: name and version? (Alexandre Devaux)
>    3. Re: Release: name and version? (Augustin Trancart)
>
>
> ----------------------------------------------------------------------
>
> Message: 1
> Date: Thu, 29 Jun 2017 14:26:50 +0200
> From: Thomas Broyer <[hidden email]>
> To: [hidden email]
> Cc: "[hidden email]" <[hidden email]>
> Subject: Re: [iTowns-dev] Video in repo
> Message-ID:
>         <CA+9O_-RNszRYn_p+A0jDm5QrTHRYD7oHdbX=[hidden email]>
> Content-Type: text/plain; charset="utf-8"
>
> 2017-06-29 13:51 GMT+02:00 Augustin Trancart <[hidden email]
>> :
>
>> I basically trust maintainer not to merge big files,
>
>
> Oh, you mean like for that video file? :troll:
>
>
>> but yes, if we can automate it, it's even better.
>
>
> Note that apparently aabc913 didn't went through a pull request, so we
> couldn't have prevented it anyway (Travis could have failed, and then a
> push-force would have been needed anyway)
>
> Cordialement,
> --
> Thomas Broyer
> Atol Conseils et Développements
> -------------- next part --------------
> An HTML attachment was scrubbed...
> URL: <http://lists.osgeo.org/pipermail/itowns-dev/attachments/20170629/c6cec9ae/attachment-0001.html>
>
> ------------------------------
>
> Message: 2
> Date: Thu, 29 Jun 2017 13:13:21 +0000
> From: Alexandre Devaux <[hidden email]>
> To: "[hidden email]" <[hidden email]>
> Subject: [iTowns-dev]  Release: name and version?
> Message-ID: <[hidden email]>
> Content-Type: text/plain; charset="Windows-1252"
>
> Hi,
>
> I would go for 1) too. "rename itowns repo into itowns-old (for instance), and we rename itowns2 into itowns"
>
>
>
>
> --
> Alexandre Devaux
> Chargé d'Etudes et de Recherche
> Laboratoire MATIS, IGN
> Tel: 01 43 98 85 73
>
> ________________________________________
> De : iTowns-dev [[hidden email]] de la part de [hidden email] [[hidden email]]
> Date d'envoi : jeudi 29 juin 2017 13:51
> À : [hidden email]
> Objet : iTowns-dev Digest, Vol 13, Issue 5
>
> Send iTowns-dev mailing list submissions to
>         [hidden email]
>
> To subscribe or unsubscribe via the World Wide Web, visit
>         https://lists.osgeo.org/mailman/listinfo/itowns-dev
> or, via email, send a message with subject or body 'help' to
>         [hidden email]
>
> You can reach the person managing the list at
>         [hidden email]
>
> When replying, please edit your Subject line so it is more specific
> than "Re: Contents of iTowns-dev digest..."
>
>
> Today's Topics:
>
>    1. Re: Video in repo (Augustin Trancart)
>    2. Re: Video in repo (Thomas Broyer)
>    3. Re: Release: name and version? (Vincent Picavet (ml))
>    4. Re: Video in repo (Vincent Picavet (ml))
>    5. Re: Video in repo (Augustin Trancart)
>
>
> ----------------------------------------------------------------------
>
> Message: 1
> Date: Thu, 29 Jun 2017 12:13:06 +0200
> From: Augustin Trancart <[hidden email]>
> To: Thomas Broyer <[hidden email]>
> Cc: "[hidden email]" <[hidden email]>
> Subject: Re: [iTowns-dev] Video in repo
> Message-ID: <[hidden email]>
> Content-Type: text/plain; charset="utf-8"
>
> Yes, agree with the idea of removing other big obsolete files as well.
>
> I'm not too worried about pull/pushes. If we require the files to be removed
> before merge, these commits would become unreachable after the force-push, and
> would eventually be garbage collected (providing we are careful at removing old
> branches).
>
> Augustin Trancart - Oslandia
> [hidden email]
>
> On 29/06/2017 12:03, Thomas Broyer wrote:
>> 15 months ago (or so), big files were added to the project and then removed, and
>> I also floated the idea of a history rewrite. I never got the "go" so it hasn't
>> been done. Iff we go that road for the video file, I suggest we also get rid of
>> those old commits.
>>
>> I don't have a strong opinion whether this should be done, but it's clear that
>> it's now or never.
>>
>> I'd suggest we eventually find a way to somehow reject pull requests (we
>> apparently can't reject commits/pushes) with big files (or many smaller files!);
>> possibly an additional check in Travis, I don't know.
>>
>> 2017-06-29 11:32 GMT+02:00 Augustin Trancart <[hidden email]
>> <mailto:[hidden email]>>:
>>
>>     Hi there!
>>
>>     Quick question with the release in sight: a video of 24M has been added (in
>>     aabc913) and removed later (in b321c01) in the repository. This makes the clone
>>     of the repository quite long even though the video is not in master any more.
>>     Should we rewrite the history to get rid of it?
>>
>>     It's possible, but it implies a force-push on master. It means that everybody
>>     will need to use "git rebase --onto master <commit-range>" for all their
>>     branches after this push is done and force-push them (and maybe a git reset
>>     --hard on their local master, I'm not sure how clever git is nowadays).
>>
>>     It's a low risk process (we'll keep a copy of the old master around), but it's a
>>     bit of a hassle and requires synchronization between us. I believe it is
>>     possible, but if we want to do it, we'd better do it now, before success hits us
>>     hard and we have thousands of contributors (yeah, I'm an optimistic kind of guy
>>     ;-) )
>>
>>     Thoughts?
>>
>>     --
>>     Augustin Trancart - Oslandia
>>     [hidden email] <mailto:[hidden email]>
>>
>>
>>     _______________________________________________
>>     iTowns-dev mailing list
>>     [hidden email] <mailto:[hidden email]>
>>     https://lists.osgeo.org/mailman/listinfo/itowns-dev
>>     <https://lists.osgeo.org/mailman/listinfo/itowns-dev>
>>
>>
>>
>>
>> --
>>
>> Cordialement,
>> --
>> Thomas Broyer
>> Atol Conseils et Développements
>>
>
> -------------- next part --------------
> A non-text attachment was scrubbed...
> Name: signature.asc
> Type: application/pgp-signature
> Size: 819 bytes
> Desc: OpenPGP digital signature
> URL: <http://lists.osgeo.org/pipermail/itowns-dev/attachments/20170629/674fd290/attachment-0001.sig>
>
> ------------------------------
>
> Message: 2
> Date: Thu, 29 Jun 2017 12:34:13 +0200
> From: Thomas Broyer <[hidden email]>
> To: [hidden email]
> Cc: "[hidden email]" <[hidden email]>
> Subject: Re: [iTowns-dev] Video in repo
> Message-ID:
>         <[hidden email]>
> Content-Type: text/plain; charset="utf-8"
>
> 2017-06-29 12:13 GMT+02:00 Augustin Trancart <[hidden email]
>> :
>
>> Yes, agree with the idea of removing other big obsolete files as well.
>>
>> I'm not too worried about pull/pushes. If we require the files to be
>> removed
>> before merge, these commits would become unreachable after the force-push,
>> and
>> would eventually be garbage collected (providing we are careful at
>> removing old
>> branches).
>
>
> Not sure I understand that last paragraph.
> My remark wrt rejecting pull requests (or pushes) with big files was to
> prevent this situation from happening again (in other words, as you said,
> "require the files to be removed before merge", but automate it).
>
> Note also that GitHub will keep the files anyway in their special
> refs/pull/ references [1], you'll just never sync them (unless you want it)
> because (by default) Git only syncs refs/heads/ and refs/tags/
> [1] https://help.github.com/articles/checking-out-pull-requests-locally/
> -------------- next part --------------
> An HTML attachment was scrubbed...
> URL: <http://lists.osgeo.org/pipermail/itowns-dev/attachments/20170629/74f11c2d/attachment-0001.html>
>
> ------------------------------
>
> Message: 3
> Date: Thu, 29 Jun 2017 12:58:19 +0200
> From: "Vincent Picavet (ml)" <[hidden email]>
> To: Thomas Broyer <[hidden email]>,
>         [hidden email]
> Cc: "[hidden email]" <[hidden email]>
> Subject: Re: [iTowns-dev] Release: name and version?
> Message-ID: <[hidden email]>
> Content-Type: text/plain; charset=utf-8
>
> Hi,
>
> On 29/06/2017 12:14, Thomas Broyer wrote:
>> FWIW, my vote would go to 1/ (particularly if we *also* rewrite the Git
>> history)
>> Rename itowns/itowns to itowns/itowns1 and itowns/itowns2 to
>> itowns/itowns, add a note to the README that iTowns 1 can be found at
>> itowns/itowns1, and release a v2 (if it makes no guarantee about API
>> stability, then label it as alpha or beta, or release candidate
>> depending on the [lack of] confidence in API [in]stability).
>>
>> Either that or finding a new name…
>
> Agree with this. Renaming itowns to itowns1 or itowns-legacy seems best
> to avoid confusion, and keep itowns name for current version.
>
> As for the name change, it could be an option, but a lot of
> communication has been made around itowns already, especially at IGN, so
> I think it would be difficult.
>
> Vincent
>
>
>>
>> 2017-06-29 11:42 GMT+02:00 Augustin Trancart
>> <[hidden email] <mailto:[hidden email]>>:
>>
>>     Hi there!
>>
>>     Our first release approaching, I have some questions about it about
>>     the package
>>     name and its version.
>>
>>     The current situation: our repo is currently called itowns2. We have
>>     the old
>>     repo called itowns. The npm package (a 0.0.0-alpha published for testing
>>     purpose) is currently called itowns[1]. I see several possibilities:
>>
>>     1/ we stick with the "itowns" name. We rename itowns repo into
>>     itowns-old (for
>>     instance), and we rename itowns2 into itowns. We release v2.0.0 on
>>     5th of July
>>     (imho we can't release another number to avoid confusion with itowns1)
>>
>>     2/ we stick with the current situation: "itowns" for the npm package
>>     only, and
>>     "itowns2" for the repo. After all, the repo is linked in the npm
>>     package page.
>>     We release a v2.0.0 for the same reason as 1/
>>
>>     3/ We keep the name itowns2 for this release everywhere. Therefore,
>>     we keep the
>>     github repo as it is and we create a new npm package named itowns2
>>     (and delete
>>     package itowns, because it is really itowns2 inside). We can release
>>     whatever
>>     version number we want.
>>
>>     4/ another combination of the above/solution?
>>
>>
>>     I don't really like current situation (aka 2/), because I think it's
>>     the most
>>     confusing setup (different name for the package and the repo, and an
>>     old itowns
>>     repo with same name as package name still in existence).
>>
>>     1/ has the advantage of reducing the confusion between itowns and
>>     itowns2
>>     (because there would be only itowns) and be clear about which one is
>>     the current
>>     one, but it forces us to rename some repos (never ideal) and release
>>     a v2
>>     (instead of a v0 or v1 for instance).
>>
>>     3/ has the advantage of being the least disruptive and the more
>>     respectful of
>>     the history of the project. If we choose this solution, we must be
>>     clear in
>>     itowns old repo that new development should be done in itowns2 repo.
>>     If we
>>     choose this, I would advocate to release a v0.something, because in
>>     semver[2],
>>     0.x.x versions do not need to have a stable API. Then we can release
>>     a v1 some
>>     weeks/months before the geoportail itowns release. It's my preferred
>>     choice.
>>
>>
>>     For a more general thought about version numbers, I would like to follow
>>     semantic versioning[2]. I think it's a great way to convey
>>     incompatible change
>>     informations to our users. For this a prerequisite would be to
>>     define our Public
>>     API. I propose a simple criterion : everything that's currently
>>     documented in
>>     our jsdoc page is our current API. Everything else is not, and we
>>     make it clear so.
>>
>>     What do you think about all that?
>>
>>     [1] https://www.npmjs.com/package/itowns
>>     <https://www.npmjs.com/package/itowns>
>>     [2] http://semver.org/
>>     --
>>     Augustin Trancart - Oslandia
>>     [hidden email] <mailto:[hidden email]>
>>
>>     PS: We can examine crazier ideas too, like another name entirely? eg
>>     Barium
>>     (Cesium is elem n°55, Barium is 56, so Cesium++ ;-) )?
>>
>>
>>     _______________________________________________
>>     iTowns-dev mailing list
>>     [hidden email] <mailto:[hidden email]>
>>     https://lists.osgeo.org/mailman/listinfo/itowns-dev
>>     <https://lists.osgeo.org/mailman/listinfo/itowns-dev>
>>
>>
>>
>>
>> --
>>
>> Cordialement,
>> --
>> Thomas Broyer
>> Atol Conseils et Développements
>>
>>
>>
>> _______________________________________________
>> iTowns-dev mailing list
>> [hidden email]
>> https://lists.osgeo.org/mailman/listinfo/itowns-dev
>>
>
>
>
> ------------------------------
>
> Message: 4
> Date: Thu, 29 Jun 2017 13:00:55 +0200
> From: "Vincent Picavet (ml)" <[hidden email]>
> To: Pierre-Eric Pelloux-Prayer
>         <[hidden email]>, [hidden email]
> Subject: Re: [iTowns-dev] Video in repo
> Message-ID: <[hidden email]>
> Content-Type: text/plain; charset=utf-8
>
> Hello,
>
> +1 also on history rewrite.
> Try to gather all big files, not just the video.
> Doing this just before the release would probably minimize the number of
> branches concerned by this change ( aka : "merge now or expect trouble"
> ;-) .
>
> Vincent
>
> On 29/06/2017 11:53, Pierre-Eric Pelloux-Prayer wrote:
>> +1 let's do this before the first release.
>>
>>
>> Le 29/06/2017 à 11:32, Augustin Trancart a écrit :
>>> Hi there!
>>>
>>> Quick question with the release in sight: a video of 24M has been added (in
>>> aabc913) and removed later (in b321c01) in the repository. This makes the clone
>>> of the repository quite long even though the video is not in master any more.
>>> Should we rewrite the history to get rid of it?
>>>
>>> It's possible, but it implies a force-push on master. It means that everybody
>>> will need to use "git rebase --onto master <commit-range>" for all their
>>> branches after this push is done and force-push them (and maybe a git reset
>>> --hard on their local master, I'm not sure how clever git is nowadays).
>>>
>>> It's a low risk process (we'll keep a copy of the old master around), but it's a
>>> bit of a hassle and requires synchronization between us. I believe it is
>>> possible, but if we want to do it, we'd better do it now, before success hits us
>>> hard and we have thousands of contributors (yeah, I'm an optimistic kind of guy
>>> ;-) )
>>>
>>> Thoughts?
>>>
>>>
>>>
>>> _______________________________________________
>>> iTowns-dev mailing list
>>> [hidden email]
>>> https://lists.osgeo.org/mailman/listinfo/itowns-dev
>>>
>> _______________________________________________
>> iTowns-dev mailing list
>> [hidden email]
>> https://lists.osgeo.org/mailman/listinfo/itowns-dev
>>
>
>
>
> ------------------------------
>
> Message: 5
> Date: Thu, 29 Jun 2017 13:51:40 +0200
> From: Augustin Trancart <[hidden email]>
> To: Thomas Broyer <[hidden email]>
> Cc: "[hidden email]" <[hidden email]>
> Subject: Re: [iTowns-dev] Video in repo
> Message-ID: <[hidden email]>
> Content-Type: text/plain; charset="utf-8"
>
> I basically trust maintainer not to merge big files, but yes, if we can automate
> it, it's even better.
>
> Augustin Trancart - Oslandia
> [hidden email]
>
> On 29/06/2017 12:34, Thomas Broyer wrote:
>>
>>
>> 2017-06-29 12:13 GMT+02:00 Augustin Trancart <[hidden email]
>> <mailto:[hidden email]>>:
>>
>>     Yes, agree with the idea of removing other big obsolete files as well.
>>
>>     I'm not too worried about pull/pushes. If we require the files to be removed
>>     before merge, these commits would become unreachable after the force-push, and
>>     would eventually be garbage collected (providing we are careful at removing old
>>     branches).
>>
>>
>> Not sure I understand that last paragraph.
>> My remark wrt rejecting pull requests (or pushes) with big files was to prevent
>> this situation from happening again (in other words, as you said, "require the
>> files to be removed before merge", but automate it).
>>
>> Note also that GitHub will keep the files anyway in their special refs/pull/
>> references [1], you'll just never sync them (unless you want it) because (by
>> default) Git only syncs refs/heads/ and refs/tags/
>> [1] https://help.github.com/articles/checking-out-pull-requests-locally/
>
> -------------- next part --------------
> A non-text attachment was scrubbed...
> Name: signature.asc
> Type: application/pgp-signature
> Size: 819 bytes
> Desc: OpenPGP digital signature
> URL: <http://lists.osgeo.org/pipermail/itowns-dev/attachments/20170629/02a1cc9b/attachment.sig>
>
> ------------------------------
>
> Subject: Digest Footer
>
> _______________________________________________
> iTowns-dev mailing list
> [hidden email]
> https://lists.osgeo.org/mailman/listinfo/itowns-dev
>
>
> ------------------------------
>
> End of iTowns-dev Digest, Vol 13, Issue 5
> *****************************************
>
>
> ------------------------------
>
> Message: 3
> Date: Thu, 29 Jun 2017 15:20:11 +0200
> From: Augustin Trancart <[hidden email]>
> To: [hidden email]
> Subject: Re: [iTowns-dev] Release: name and version?
> Message-ID: <[hidden email]>
> Content-Type: text/plain; charset="utf-8"
>
> Ok, at the moment it seems there is a consensus for going with 1/.
>
> I propose to do the dull work of renaming repos on the 4th of July, if no
> objection until then (or everything including the release on the 5th).
>
> so itowns -> itowns-legacy (+ a link in the README)
>    itowns2 -> itowns
>
> I guess the released version number would be v2? Or something else?
>
> Augustin Trancart - Oslandia
> [hidden email]
>
> On 29/06/2017 15:13, Alexandre Devaux wrote:
>> Hi,
>>
>> I would go for 1) too. "rename itowns repo into itowns-old (for instance), and we rename itowns2 into itowns"
>>
>>
>>
>>
>> --
>> Alexandre Devaux
>> Chargé d'Etudes et de Recherche
>> Laboratoire MATIS, IGN
>> Tel: 01 43 98 85 73
>>
>> ________________________________________
>> De : iTowns-dev [[hidden email]] de la part de [hidden email] [[hidden email]]
>> Date d'envoi : jeudi 29 juin 2017 13:51
>> À : [hidden email]
>> Objet : iTowns-dev Digest, Vol 13, Issue 5
>>
>> Send iTowns-dev mailing list submissions to
>>         [hidden email]
>>
>> To subscribe or unsubscribe via the World Wide Web, visit
>>         https://lists.osgeo.org/mailman/listinfo/itowns-dev
>> or, via email, send a message with subject or body 'help' to
>>         [hidden email]
>>
>> You can reach the person managing the list at
>>         [hidden email]
>>
>> When replying, please edit your Subject line so it is more specific
>> than "Re: Contents of iTowns-dev digest..."
>>
>>
>> Today's Topics:
>>
>>    1. Re: Video in repo (Augustin Trancart)
>>    2. Re: Video in repo (Thomas Broyer)
>>    3. Re: Release: name and version? (Vincent Picavet (ml))
>>    4. Re: Video in repo (Vincent Picavet (ml))
>>    5. Re: Video in repo (Augustin Trancart)
>>
>>
>> ----------------------------------------------------------------------
>>
>> Message: 1
>> Date: Thu, 29 Jun 2017 12:13:06 +0200
>> From: Augustin Trancart <[hidden email]>
>> To: Thomas Broyer <[hidden email]>
>> Cc: "[hidden email]" <[hidden email]>
>> Subject: Re: [iTowns-dev] Video in repo
>> Message-ID: <[hidden email]>
>> Content-Type: text/plain; charset="utf-8"
>>
>> Yes, agree with the idea of removing other big obsolete files as well.
>>
>> I'm not too worried about pull/pushes. If we require the files to be removed
>> before merge, these commits would become unreachable after the force-push, and
>> would eventually be garbage collected (providing we are careful at removing old
>> branches).
>>
>> Augustin Trancart - Oslandia
>> [hidden email]
>>
>> On 29/06/2017 12:03, Thomas Broyer wrote:
>>> 15 months ago (or so), big files were added to the project and then removed, and
>>> I also floated the idea of a history rewrite. I never got the "go" so it hasn't
>>> been done. Iff we go that road for the video file, I suggest we also get rid of
>>> those old commits.
>>>
>>> I don't have a strong opinion whether this should be done, but it's clear that
>>> it's now or never.
>>>
>>> I'd suggest we eventually find a way to somehow reject pull requests (we
>>> apparently can't reject commits/pushes) with big files (or many smaller files!);
>>> possibly an additional check in Travis, I don't know.
>>>
>>> 2017-06-29 11:32 GMT+02:00 Augustin Trancart <[hidden email]
>>> <mailto:[hidden email]>>:
>>>
>>>     Hi there!
>>>
>>>     Quick question with the release in sight: a video of 24M has been added (in
>>>     aabc913) and removed later (in b321c01) in the repository. This makes the clone
>>>     of the repository quite long even though the video is not in master any more.
>>>     Should we rewrite the history to get rid of it?
>>>
>>>     It's possible, but it implies a force-push on master. It means that everybody
>>>     will need to use "git rebase --onto master <commit-range>" for all their
>>>     branches after this push is done and force-push them (and maybe a git reset
>>>     --hard on their local master, I'm not sure how clever git is nowadays).
>>>
>>>     It's a low risk process (we'll keep a copy of the old master around), but it's a
>>>     bit of a hassle and requires synchronization between us. I believe it is
>>>     possible, but if we want to do it, we'd better do it now, before success hits us
>>>     hard and we have thousands of contributors (yeah, I'm an optimistic kind of guy
>>>     ;-) )
>>>
>>>     Thoughts?
>>>
>>>     --
>>>     Augustin Trancart - Oslandia
>>>     [hidden email] <mailto:[hidden email]>
>>>
>>>
>>>     _______________________________________________
>>>     iTowns-dev mailing list
>>>     [hidden email] <mailto:[hidden email]>
>>>     https://lists.osgeo.org/mailman/listinfo/itowns-dev
>>>     <https://lists.osgeo.org/mailman/listinfo/itowns-dev>
>>>
>>>
>>>
>>>
>>> --
>>>
>>> Cordialement,
>>> --
>>> Thomas Broyer
>>> Atol Conseils et Développements
>>>
>>
>> -------------- next part --------------
>> A non-text attachment was scrubbed...
>> Name: signature.asc
>> Type: application/pgp-signature
>> Size: 819 bytes
>> Desc: OpenPGP digital signature
>> URL: <http://lists.osgeo.org/pipermail/itowns-dev/attachments/20170629/674fd290/attachment-0001.sig>
>>
>> ------------------------------
>>
>> Message: 2
>> Date: Thu, 29 Jun 2017 12:34:13 +0200
>> From: Thomas Broyer <[hidden email]>
>> To: [hidden email]
>> Cc: "[hidden email]" <[hidden email]>
>> Subject: Re: [iTowns-dev] Video in repo
>> Message-ID:
>>         <[hidden email]>
>> Content-Type: text/plain; charset="utf-8"
>>
>> 2017-06-29 12:13 GMT+02:00 Augustin Trancart <[hidden email]
>>> :
>>
>>> Yes, agree with the idea of removing other big obsolete files as well.
>>>
>>> I'm not too worried about pull/pushes. If we require the files to be
>>> removed
>>> before merge, these commits would become unreachable after the force-push,
>>> and
>>> would eventually be garbage collected (providing we are careful at
>>> removing old
>>> branches).
>>
>>
>> Not sure I understand that last paragraph.
>> My remark wrt rejecting pull requests (or pushes) with big files was to
>> prevent this situation from happening again (in other words, as you said,
>> "require the files to be removed before merge", but automate it).
>>
>> Note also that GitHub will keep the files anyway in their special
>> refs/pull/ references [1], you'll just never sync them (unless you want it)
>> because (by default) Git only syncs refs/heads/ and refs/tags/
>> [1] https://help.github.com/articles/checking-out-pull-requests-locally/
>> -------------- next part --------------
>> An HTML attachment was scrubbed...
>> URL: <http://lists.osgeo.org/pipermail/itowns-dev/attachments/20170629/74f11c2d/attachment-0001.html>
>>
>> ------------------------------
>>
>> Message: 3
>> Date: Thu, 29 Jun 2017 12:58:19 +0200
>> From: "Vincent Picavet (ml)" <[hidden email]>
>> To: Thomas Broyer <[hidden email]>,
>>         [hidden email]
>> Cc: "[hidden email]" <[hidden email]>
>> Subject: Re: [iTowns-dev] Release: name and version?
>> Message-ID: <[hidden email]>
>> Content-Type: text/plain; charset=utf-8
>>
>> Hi,
>>
>> On 29/06/2017 12:14, Thomas Broyer wrote:
>>> FWIW, my vote would go to 1/ (particularly if we *also* rewrite the Git
>>> history)
>>> Rename itowns/itowns to itowns/itowns1 and itowns/itowns2 to
>>> itowns/itowns, add a note to the README that iTowns 1 can be found at
>>> itowns/itowns1, and release a v2 (if it makes no guarantee about API
>>> stability, then label it as alpha or beta, or release candidate
>>> depending on the [lack of] confidence in API [in]stability).
>>>
>>> Either that or finding a new name…
>>
>> Agree with this. Renaming itowns to itowns1 or itowns-legacy seems best
>> to avoid confusion, and keep itowns name for current version.
>>
>> As for the name change, it could be an option, but a lot of
>> communication has been made around itowns already, especially at IGN, so
>> I think it would be difficult.
>>
>> Vincent
>>
>>
>>>
>>> 2017-06-29 11:42 GMT+02:00 Augustin Trancart
>>> <[hidden email] <mailto:[hidden email]>>:
>>>
>>>     Hi there!
>>>
>>>     Our first release approaching, I have some questions about it about
>>>     the package
>>>     name and its version.
>>>
>>>     The current situation: our repo is currently called itowns2. We have
>>>     the old
>>>     repo called itowns. The npm package (a 0.0.0-alpha published for testing
>>>     purpose) is currently called itowns[1]. I see several possibilities:
>>>
>>>     1/ we stick with the "itowns" name. We rename itowns repo into
>>>     itowns-old (for
>>>     instance), and we rename itowns2 into itowns. We release v2.0.0 on
>>>     5th of July
>>>     (imho we can't release another number to avoid confusion with itowns1)
>>>
>>>     2/ we stick with the current situation: "itowns" for the npm package
>>>     only, and
>>>     "itowns2" for the repo. After all, the repo is linked in the npm
>>>     package page.
>>>     We release a v2.0.0 for the same reason as 1/
>>>
>>>     3/ We keep the name itowns2 for this release everywhere. Therefore,
>>>     we keep the
>>>     github repo as it is and we create a new npm package named itowns2
>>>     (and delete
>>>     package itowns, because it is really itowns2 inside). We can release
>>>     whatever
>>>     version number we want.
>>>
>>>     4/ another combination of the above/solution?
>>>
>>>
>>>     I don't really like current situation (aka 2/), because I think it's
>>>     the most
>>>     confusing setup (different name for the package and the repo, and an
>>>     old itowns
>>>     repo with same name as package name still in existence).
>>>
>>>     1/ has the advantage of reducing the confusion between itowns and
>>>     itowns2
>>>     (because there would be only itowns) and be clear about which one is
>>>     the current
>>>     one, but it forces us to rename some repos (never ideal) and release
>>>     a v2
>>>     (instead of a v0 or v1 for instance).
>>>
>>>     3/ has the advantage of being the least disruptive and the more
>>>     respectful of
>>>     the history of the project. If we choose this solution, we must be
>>>     clear in
>>>     itowns old repo that new development should be done in itowns2 repo.
>>>     If we
>>>     choose this, I would advocate to release a v0.something, because in
>>>     semver[2],
>>>     0.x.x versions do not need to have a stable API. Then we can release
>>>     a v1 some
>>>     weeks/months before the geoportail itowns release. It's my preferred
>>>     choice.
>>>
>>>
>>>     For a more general thought about version numbers, I would like to follow
>>>     semantic versioning[2]. I think it's a great way to convey
>>>     incompatible change
>>>     informations to our users. For this a prerequisite would be to
>>>     define our Public
>>>     API. I propose a simple criterion : everything that's currently
>>>     documented in
>>>     our jsdoc page is our current API. Everything else is not, and we
>>>     make it clear so.
>>>
>>>     What do you think about all that?
>>>
>>>     [1] https://www.npmjs.com/package/itowns
>>>     <https://www.npmjs.com/package/itowns>
>>>     [2] http://semver.org/
>>>     --
>>>     Augustin Trancart - Oslandia
>>>     [hidden email] <mailto:[hidden email]>
>>>
>>>     PS: We can examine crazier ideas too, like another name entirely? eg
>>>     Barium
>>>     (Cesium is elem n°55, Barium is 56, so Cesium++ ;-) )?
>>>
>>>
>>>     _______________________________________________
>>>     iTowns-dev mailing list
>>>     [hidden email] <mailto:[hidden email]>
>>>     https://lists.osgeo.org/mailman/listinfo/itowns-dev
>>>     <https://lists.osgeo.org/mailman/listinfo/itowns-dev>
>>>
>>>
>>>
>>>
>>> --
>>>
>>> Cordialement,
>>> --
>>> Thomas Broyer
>>> Atol Conseils et Développements
>>>
>>>
>>>
>>> _______________________________________________
>>> iTowns-dev mailing list
>>> [hidden email]
>>> https://lists.osgeo.org/mailman/listinfo/itowns-dev
>>>
>>
>>
>>
>> ------------------------------
>>
>> Message: 4
>> Date: Thu, 29 Jun 2017 13:00:55 +0200
>> From: "Vincent Picavet (ml)" <[hidden email]>
>> To: Pierre-Eric Pelloux-Prayer
>>         <[hidden email]>, [hidden email]
>> Subject: Re: [iTowns-dev] Video in repo
>> Message-ID: <[hidden email]>
>> Content-Type: text/plain; charset=utf-8
>>
>> Hello,
>>
>> +1 also on history rewrite.
>> Try to gather all big files, not just the video.
>> Doing this just before the release would probably minimize the number of
>> branches concerned by this change ( aka : "merge now or expect trouble"
>> ;-) .
>>
>> Vincent
>>
>> On 29/06/2017 11:53, Pierre-Eric Pelloux-Prayer wrote:
>>> +1 let's do this before the first release.
>>>
>>>
>>> Le 29/06/2017 à 11:32, Augustin Trancart a écrit :
>>>> Hi there!
>>>>
>>>> Quick question with the release in sight: a video of 24M has been added (in
>>>> aabc913) and removed later (in b321c01) in the repository. This makes the clone
>>>> of the repository quite long even though the video is not in master any more.
>>>> Should we rewrite the history to get rid of it?
>>>>
>>>> It's possible, but it implies a force-push on master. It means that everybody
>>>> will need to use "git rebase --onto master <commit-range>" for all their
>>>> branches after this push is done and force-push them (and maybe a git reset
>>>> --hard on their local master, I'm not sure how clever git is nowadays).
>>>>
>>>> It's a low risk process (we'll keep a copy of the old master around), but it's a
>>>> bit of a hassle and requires synchronization between us. I believe it is
>>>> possible, but if we want to do it, we'd better do it now, before success hits us
>>>> hard and we have thousands of contributors (yeah, I'm an optimistic kind of guy
>>>> ;-) )
>>>>
>>>> Thoughts?
>>>>
>>>>
>>>>
>>>> _______________________________________________
>>>> iTowns-dev mailing list
>>>> [hidden email]
>>>> https://lists.osgeo.org/mailman/listinfo/itowns-dev
>>>>
>>> _______________________________________________
>>> iTowns-dev mailing list
>>> [hidden email]
>>> https://lists.osgeo.org/mailman/listinfo/itowns-dev
>>>
>>
>>
>>
>> ------------------------------
>>
>> Message: 5
>> Date: Thu, 29 Jun 2017 13:51:40 +0200
>> From: Augustin Trancart <[hidden email]>
>> To: Thomas Broyer <[hidden email]>
>> Cc: "[hidden email]" <[hidden email]>
>> Subject: Re: [iTowns-dev] Video in repo
>> Message-ID: <[hidden email]>
>> Content-Type: text/plain; charset="utf-8"
>>
>> I basically trust maintainer not to merge big files, but yes, if we can automate
>> it, it's even better.
>>
>> Augustin Trancart - Oslandia
>> [hidden email]
>>
>> On 29/06/2017 12:34, Thomas Broyer wrote:
>>>
>>>
>>> 2017-06-29 12:13 GMT+02:00 Augustin Trancart <[hidden email]
>>> <mailto:[hidden email]>>:
>>>
>>>     Yes, agree with the idea of removing other big obsolete files as well.
>>>
>>>     I'm not too worried about pull/pushes. If we require the files to be removed
>>>     before merge, these commits would become unreachable after the force-push, and
>>>     would eventually be garbage collected (providing we are careful at removing old
>>>     branches).
>>>
>>>
>>> Not sure I understand that last paragraph.
>>> My remark wrt rejecting pull requests (or pushes) with big files was to prevent
>>> this situation from happening again (in other words, as you said, "require the
>>> files to be removed before merge", but automate it).
>>>
>>> Note also that GitHub will keep the files anyway in their special refs/pull/
>>> references [1], you'll just never sync them (unless you want it) because (by
>>> default) Git only syncs refs/heads/ and refs/tags/
>>> [1] https://help.github.com/articles/checking-out-pull-requests-locally/
>>
>> -------------- next part --------------
>> A non-text attachment was scrubbed...
>> Name: signature.asc
>> Type: application/pgp-signature
>> Size: 819 bytes
>> Desc: OpenPGP digital signature
>> URL: <http://lists.osgeo.org/pipermail/itowns-dev/attachments/20170629/02a1cc9b/attachment.sig>
>>
>> ------------------------------
>>
>> Subject: Digest Footer
>>
>> _______________________________________________
>> iTowns-dev mailing list
>> [hidden email]
>> https://lists.osgeo.org/mailman/listinfo/itowns-dev
>>
>>
>> ------------------------------
>>
>> End of iTowns-dev Digest, Vol 13, Issue 5
>> *****************************************
>> _______________________________________________
>> iTowns-dev mailing list
>> [hidden email]
>> https://lists.osgeo.org/mailman/listinfo/itowns-dev
>>
>
> -------------- next part --------------
> A non-text attachment was scrubbed...
> Name: signature.asc
> Type: application/pgp-signature
> Size: 819 bytes
> Desc: OpenPGP digital signature
> URL: <http://lists.osgeo.org/pipermail/itowns-dev/attachments/20170629/00b7f3e0/attachment.sig>
>
> ------------------------------
>
> Subject: Digest Footer
>
> _______________________________________________
> iTowns-dev mailing list
> [hidden email]
> https://lists.osgeo.org/mailman/listinfo/itowns-dev
>
>
> ------------------------------
>
> End of iTowns-dev Digest, Vol 13, Issue 6
> *****************************************
> _______________________________________________
> iTowns-dev mailing list
> [hidden email]
> https://lists.osgeo.org/mailman/listinfo/itowns-dev
>

_______________________________________________
iTowns-dev mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/itowns-dev

signature.asc (836 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Tutorials

Alexandre Devaux
In reply to this post by Alexandre Devaux

> I can start to work on the website and make a PR when I have the first pass
> ready, WDYT?

Super glad of it :)

> I really like the three.js/docs layout.
> On the same page you get access to: tutorials/introduction articles, API
> documentation and examples.

Yes this way is quite powerful I really like it too!

>  I believe that, as iTowns' users will also be three.js users,  it makes sense to try to match the style and
> organization of three.js website.
> I guess that all the discussed tools have configurable layout/template, so it shouldn't be too hard to achieve.

Yes, it is a major point that we are using THREEJS so the vast majority of 3D web coders could use itowns easily so some nice reference of it are always good.
Nevertheless iTowns target the geospatial world so we should find a nice mix that suit 3d freaks and people coming for effortless light web mapping




--
Alexandre Devaux
Chargé d'Etudes et de Recherche
Laboratoire MATIS, IGN
Tel: 01 43 98 85 73

________________________________________
De : iTowns-dev [[hidden email]] de la part de [hidden email] [[hidden email]]
Date d'envoi : vendredi 30 juin 2017 10:11
À : [hidden email]
Objet : iTowns-dev Digest, Vol 13, Issue 8

Send iTowns-dev mailing list submissions to
        [hidden email]

To subscribe or unsubscribe via the World Wide Web, visit
        https://lists.osgeo.org/mailman/listinfo/itowns-dev
or, via email, send a message with subject or body 'help' to
        [hidden email]

You can reach the person managing the list at
        [hidden email]

When replying, please edit your Subject line so it is more specific
than "Re: Contents of iTowns-dev digest..."


Today's Topics:

   1. Re: Tutorials (Pierre-Eric Pelloux-Prayer)
   2. Re: Tutorials (Augustin Trancart)


----------------------------------------------------------------------

Message: 1
Date: Fri, 30 Jun 2017 09:11:13 +0200
From: Pierre-Eric Pelloux-Prayer
        <[hidden email]>
To: [hidden email]
Subject: Re: [iTowns-dev] Tutorials
Message-ID: <[hidden email]>
Content-Type: text/plain; charset=utf-8

Hi,

>
> Victor and I wrote a draft for tutorials (some of it is obsolete), in the readme here:
> https://github.com/iTowns/itowns2/tree/README

Good idea, and thanks for working on the documentation topic.


>
> I think ideally we should have a tutorials page which list all tutorials which will have their own page.
>
> Something like:
> itowns-project.org/tutorials.html
>   itowns-project.org/tutorials/basicstartup.html
>   itowns-project.org/tutorials/addGeometryTutorial.html
>   ...
>

I really like the three.js/docs layout.
On the same page you get access to: tutorials/introduction articles, API documentation and examples.

One big + is that you can just type something in the search bar (eg: Material) and you get to discover
everything available on the subject.


> If you have other ideas on that topic don't hesitate!

Here are 3 independant ideas:

1. for examples/tutorials, I think litterate programming offers a nice solution.

A big part of https://github.com/iTowns/itowns2/blob/README/README.md is a copy paste of index.html.
I see at least 2 benefits to write the same content direclty in index.html:
  - index.html would become documented :)
  - the comments would be easier to keep synchronized with itowns changes (it's too easy to forget to
    update the README.md or addGeometry.md)

2. consistent documentation style for examples and API

See issue https://github.com/iTowns/itowns2/issues/314 (discussing jsdoc, docco and other tools for API doc)

Also it could make sense to use a single tool to build our website (instead of jekyll + API doc tool + examples/tutorial
doc tool).
Here's what I imagined: docco for API/examples doc and a static landing page showing the README.md + screenshots of
itowns app (like https://threejs.org/).

3. I believe that, as iTowns' users will also be three.js users,  it makes sense to try to match the style and
organization of three.js website.
I guess that all the discussed tools have configurable layout/template, so it shouldn't be too hard to achieve.


Regards,
Pierre-Eric



------------------------------

Message: 2
Date: Fri, 30 Jun 2017 10:11:48 +0200
From: Augustin Trancart <[hidden email]>
To: [hidden email]
Subject: Re: [iTowns-dev] Tutorials
Message-ID: <[hidden email]>
Content-Type: text/plain; charset="utf-8"

Hi !

Great for the README, I'll try to comment on it today.


On 29/06/2017 19:29, Alexandre Devaux wrote:

> Hi folks,
>
> Victor and I wrote a draft for tutorials (some of it is obsolete), in the readme here:
> https://github.com/iTowns/itowns2/tree/README
>
> I think ideally we should have a tutorials page which list all tutorials which will have their own page.
>
> Something like:
> itowns-project.org/tutorials.html
>   itowns-project.org/tutorials/basicstartup.html
>   itowns-project.org/tutorials/addGeometryTutorial.html
>   ...

Yep, but AFAIK we don't have tutorials yet, right? As the release is next week,
we might not have time to write those. Let's add a tutorial section when the
first one is written.

>
> Currently the website is on https://github.com/iTowns/itowns.github.io, we could store images of examples there.

Let's be more ambitious and store real, working examples in the landing page!
After all itowns is web-based, images are so 1990 ;-) One implication of this:
we should detect if the user is on an unsupported browser, and either display a
warning or display a screenshot instead (or both)? Or we don't care, considering
that most of our visitors would be from supported browsers?

I can start to work on the website and make a PR when I have the first pass
ready, WDYT?

>
> If you have other ideas on that topic don't hesitate!
>
> Feel free to contribute on https://github.com/iTowns/itowns2/tree/README

Thanks!

>
> Alexandre

I carry on:

On 30/06/2017 09:11, Pierre-Eric Pelloux-Prayer wrote:
>>
>> I think ideally we should have a tutorials page which list all tutorials
which will have their own page.

>>
>> Something like:
>> itowns-project.org/tutorials.html
>>   itowns-project.org/tutorials/basicstartup.html
>>   itowns-project.org/tutorials/addGeometryTutorial.html
>>   ...
>>
>
> I really like the three.js/docs layout.
> On the same page you get access to: tutorials/introduction articles, API
documentation and examples.

Agreed.

>
> One big + is that you can just type something in the search bar (eg: Material)
and you get to discover
> everything available on the subject.

We *need* that. I'll work on this.

>
>> If you have other ideas on that topic don't hesitate!
>
> Here are 3 independant ideas:
>
> 1. for examples/tutorials, I think litterate programming offers a nice solution.

That's clearly a big plus on docco for the examples.

>
> 2. consistent documentation style for examples and API
>
> See issue https://github.com/iTowns/itowns2/issues/314 (discussing jsdoc,
docco and other tools for API doc)
>
> Also it could make sense to use a single tool to build our website (instead of
jekyll + API doc tool + examples/tutorial
> doc tool).

Not necessarily... I don't know: it might cause more pain that it solves. It
depends what we want in the website (do we want individual pages that are
neither api doc nor examples?)


>
>
> Regards,
> Pierre-Eric

Same ;-)

Augustin Trancart - Oslandia





>
> ________________________________________
> De : iTowns-dev [[hidden email]] de la part de [hidden email] [[hidden email]]
> Date d'envoi : jeudi 29 juin 2017 15:20
> À : [hidden email]
> Objet : iTowns-dev Digest, Vol 13, Issue 6
>
> Send iTowns-dev mailing list submissions to
>         [hidden email]
>
> To subscribe or unsubscribe via the World Wide Web, visit
>         https://lists.osgeo.org/mailman/listinfo/itowns-dev
> or, via email, send a message with subject or body 'help' to
>         [hidden email]
>
> You can reach the person managing the list at
>         [hidden email]
>
> When replying, please edit your Subject line so it is more specific
> than "Re: Contents of iTowns-dev digest..."
>
>
> Today's Topics:
>
>    1. Re: Video in repo (Thomas Broyer)
>    2.  Release: name and version? (Alexandre Devaux)
>    3. Re: Release: name and version? (Augustin Trancart)
>
>
_______________________________________________
iTowns-dev mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/itowns-dev