[docs] Dedup and improve Getting Sources section #1551

pastk · 2021-11-13T16:18:20Z

pastk commented

2021-11-13 16:18:20 +00:00

As per discussion https://github.com/organicmaps/organicmaps/discussions/1538

I'm not sure if we need a special case for Win10 bash ./configure.sh?

Also please check my thoughts on using shallow clone for submodules - do you think it'll work like that? (I'm using shallow submodules right now and builds are working fine).

As per discussion https://github.com/organicmaps/organicmaps/discussions/1538 I'm not sure if we need a special case for Win10 `bash ./configure.sh`? Also please check my thoughts on using shallow clone for submodules - do you think it'll work like that? (I'm using shallow submodules right now and builds are working fine).

biodranik (Migrated from github.com) reviewed 2021-11-14 13:27:42 +00:00

docs/INSTALL.md

					
				@ -7,0 +17,4 @@

				git config --global core.symlinks true

				```

				If you plan to contribute and propose pull requests then fork the repo https://github.com/organicmaps/organicmaps first.

biodranik (Migrated from github.com) commented

2021-11-14 13:18:39 +00:00

Maybe move this to CONTRIBUTE and reference it here?

docs/INSTALL.md

					
				@ -7,0 +29,4 @@

				git clone https://github.com/<your-github-name>/organicmaps.git

				```

				Add a `--filter=blob:limit=128k` option to above command to make a _partial clone_ of just ~1.2Gb, i.e. blob files over 128k in size will be excluded form the history and downloaded on-demand - should be suitable for a generic development use.

biodranik (Migrated from github.com) commented

2021-11-14 13:20:51 +00:00

Move to contribute block. But is it really necessary? If you want to contribute, then cloning everything is the most reliable way.

s/form/from/

Move to contribute block. But is it really necessary? If you want to contribute, then cloning everything is the most reliable way. s/form/from/

docs/INSTALL.md

					
				@ -7,0 +31,4 @@

				Add a `--filter=blob:limit=128k` option to above command to make a _partial clone_ of just ~1.2Gb, i.e. blob files over 128k in size will be excluded form the history and downloaded on-demand - should be suitable for a generic development use.

				And/or add a `--depth=1` option to make a _shallow copy_ (and possibly a `--no-single-branch` to have all branches not just `master`), i.e. omit history retaining current commits only - suitable for one-off builds.

biodranik (Migrated from github.com) commented

2021-11-14 13:23:05 +00:00

Let's put it into the clone cmd together with --recurse-submodules.

The install doc should show the simplest and the fastest way to build and run. All dev details can be stored in contributing doc. What do you think?

Let's put it into the clone cmd together with --recurse-submodules. The install doc should show the simplest and the fastest way to build and run. All dev details can be stored in contributing doc. What do you think?

docs/INSTALL.md

					
				@ -7,0 +38,4 @@

				cd organicmaps

				```

				Clone git submodules (~3Gb):

biodranik (Migrated from github.com) commented

2021-11-14 13:24:34 +00:00

It can be done in the clone command. Let's simplify it.

docs/INSTALL.md

biodranik (Migrated from github.com) commented

2021-11-14 13:26:03 +00:00

-r for release build, -d for debug one

This command builds for the desktop.

-r for release build, -d for debug one This command builds for the desktop.

pastk reviewed 2021-11-14 15:34:40 +00:00

docs/INSTALL.md

					
				@ -7,0 +31,4 @@

				Add a `--filter=blob:limit=128k` option to above command to make a _partial clone_ of just ~1.2Gb, i.e. blob files over 128k in size will be excluded form the history and downloaded on-demand - should be suitable for a generic development use.

				And/or add a `--depth=1` option to make a _shallow copy_ (and possibly a `--no-single-branch` to have all branches not just `master`), i.e. omit history retaining current commits only - suitable for one-off builds.

pastk commented

2021-11-14 15:34:39 +00:00

I understand your idea of separating contribution and installation docs.

For the reference, at the moment CONTRIBUTING.md says:

Code Contributions

Please follow instructions in INSTALL.md to set up your development environment. Create and submit a Pull Request with your changes.

I think its possible to separate but it'll mean a lot of duplication, basically the bulk of current INSTALL.md would be moved to CONTRIBUTING.md and then INSTALL.md simplified.

How do we define a build/run-only env? For that case I think there is no need for Android Studio and actually the fastest way to get the repo would be shallow/partial clone as it reduces download times drastically.

I'd rather prefer the current approach with a detailed doc that gives a default/straightforward way of doing things alongside some options so the one following it can make decisions on the go.

A compromise would be to hide most of the optional things in e.g. footnotes or a separate subsection so that the "default way" is more clear.

Please let me know your further thoughts on this!

I understand your idea of separating contribution and installation docs. For the reference, at the moment `CONTRIBUTING.md` says: > Code Contributions > > Please follow instructions in INSTALL.md to set up your development environment. Create and submit a Pull Request with your changes. I think its possible to separate but it'll mean a lot of duplication, basically the bulk of current `INSTALL.md` would be moved to `CONTRIBUTING.md` and then `INSTALL.md` simplified. How do we define a build/run-only env? For that case I think there is no need for Android Studio and actually the fastest way to get the repo would be shallow/partial clone as it reduces download times drastically. I'd rather prefer the current approach with a detailed doc that gives a default/straightforward way of doing things alongside some options so the one following it can make decisions on the go. A compromise would be to hide most of the optional things in e.g. footnotes or a separate subsection so that the "default way" is more clear. Please let me know your further thoughts on this!

pastk reviewed 2021-11-14 15:42:03 +00:00

docs/INSTALL.md

					
				@ -7,0 +29,4 @@

				git clone https://github.com/<your-github-name>/organicmaps.git

				```

				Add a `--filter=blob:limit=128k` option to above command to make a _partial clone_ of just ~1.2Gb, i.e. blob files over 128k in size will be excluded form the history and downloaded on-demand - should be suitable for a generic development use.

pastk commented

2021-11-14 15:42:03 +00:00

Its not necessary of course, its just a way to lower barriers for people with low-spec machines and limited/slow Internet.

E.g. my laptop's SSD is 120Gb, devoting 30+Gb to be able to contribute to OM is a lot.
Cloning the full repo took me an hour almost and I was lucky to have an unlimited wifi for that - usually I'm on a limited plan.

Though I agree those options could be moved somewhere in footnotes or a special subsection perhaps.

Its not necessary of course, its just a way to lower barriers for people with low-spec machines and limited/slow Internet. E.g. my laptop's SSD is 120Gb, devoting 30+Gb to be able to contribute to OM is a lot. Cloning the full repo took me an hour almost and I was lucky to have an unlimited wifi for that - usually I'm on a limited plan. Though I agree those options could be moved somewhere in footnotes or a special subsection perhaps.

pastk reviewed 2021-11-14 18:35:40 +00:00

docs/INSTALL.md

pastk commented

2021-11-14 18:35:40 +00:00

These options are present in the doc already, they're just not visible in the diff.

pastk reviewed 2021-11-14 18:56:39 +00:00

docs/INSTALL.md

					
				@ -7,0 +17,4 @@

				git config --global core.symlinks true

				```

				If you plan to contribute and propose pull requests then fork the repo https://github.com/organicmaps/organicmaps first.

pastk commented

2021-11-14 18:56:39 +00:00

I don't see a way how to make it elegant and easy to read unless its duplicated...

E.g. imagine in INSTALL we'd have

If you're planning to contribute your changes then read CONTRIB first.
Clone the repo:
git clone ....

And in the CONTRIB

Fork the repo first and then follow instructions in INSTALL to clone it.

Not good as people will forget to substitute their github name in the clone command.

or

Fork the repo first and then clone it
git clone <forked-repo>...
Follow instructions in INSTALL#configure to configure the cloned repo.

Better, but requires a reader to jump back-and-forth between the two docs still.

And if we'll add e.g. options to reduce download size (from below) to CONTRIB and cross-reference them to INSTALL then it'll become more ugly even.

Maybe I just didn't get your idea right though.

I don't see a way how to make it elegant and easy to read unless its duplicated... E.g. imagine in INSTALL we'd have > If you're planning to contribute your changes then read CONTRIB first. > Clone the repo: > `git clone ....` And in the CONTRIB > Fork the repo first and then follow instructions in INSTALL to clone it. Not good as people will forget to substitute their github name in the clone command. or > Fork the repo first and then clone it > `git clone <forked-repo>...` > Follow instructions in INSTALL#configure to configure the cloned repo. Better, but requires a reader to jump back-and-forth between the two docs still. And if we'll add e.g. options to reduce download size (from below) to CONTRIB and cross-reference them to INSTALL then it'll become more ugly even. Maybe I just didn't get your idea right though.

biodranik (Migrated from github.com) reviewed 2021-11-14 21:27:02 +00:00

docs/INSTALL.md

					
				@ -7,0 +31,4 @@

				Add a `--filter=blob:limit=128k` option to above command to make a _partial clone_ of just ~1.2Gb, i.e. blob files over 128k in size will be excluded form the history and downloaded on-demand - should be suitable for a generic development use.

				And/or add a `--depth=1` option to make a _shallow copy_ (and possibly a `--no-single-branch` to have all branches not just `master`), i.e. omit history retaining current commits only - suitable for one-off builds.

biodranik (Migrated from github.com) commented

2021-11-14 21:27:02 +00:00

Current docs are hard for newcomers. It would be great if there will be an "easy and fast" way to compile and run the app on Android, iOS, and Desktops. Also, ideally, if someone wants to make a very simple code change/fix, it should also be very easy and clear. And in parallel, there could be a very detailed doc for those who want to get all details.

I don't know how to better organize it. Any ideas are welcome.

Current docs are hard for newcomers. It would be great if there will be an "easy and fast" way to compile and run the app on Android, iOS, and Desktops. Also, ideally, if someone wants to make a very simple code change/fix, it should also be very easy and clear. And in parallel, there could be a very detailed doc for those who want to get all details. I don't know how to better organize it. Any ideas are welcome.

biodranik (Migrated from github.com) reviewed 2021-11-14 21:28:51 +00:00

docs/INSTALL.md

					
				@ -7,0 +31,4 @@

				Add a `--filter=blob:limit=128k` option to above command to make a _partial clone_ of just ~1.2Gb, i.e. blob files over 128k in size will be excluded form the history and downloaded on-demand - should be suitable for a generic development use.

				And/or add a `--depth=1` option to make a _shallow copy_ (and possibly a `--no-single-branch` to have all branches not just `master`), i.e. omit history retaining current commits only - suitable for one-off builds.

biodranik (Migrated from github.com) commented

2021-11-14 21:28:50 +00:00

Maybe make starting INSTALL sections simple, but move all details to sections below? And insert some links to them to avoid duplication?

biodranik (Migrated from github.com) reviewed 2021-11-14 21:47:13 +00:00

docs/INSTALL.md

					
				@ -7,0 +17,4 @@

				git config --global core.symlinks true

				```

				If you plan to contribute and propose pull requests then fork the repo https://github.com/organicmaps/organicmaps first.

biodranik (Migrated from github.com) commented

2021-11-14 21:47:12 +00:00

To avoid duplication, we can write in INSTALL that use this git clone … if you just want to build it for yourself and save disk space, or that git clone… if you want to contribute.

To avoid duplication, we can write in INSTALL that use this `git clone …` if you just want to build it for yourself and save disk space, or that `git clone…` if you want to contribute.

biodranik (Migrated from github.com) reviewed 2021-11-14 21:47:46 +00:00

docs/INSTALL.md

					
				@ -7,0 +17,4 @@

				git config --global core.symlinks true

				```

				If you plan to contribute and propose pull requests then fork the repo https://github.com/organicmaps/organicmaps first.

biodranik (Migrated from github.com) commented

2021-11-14 21:47:46 +00:00

And then start CONTRIBUTING with "Please follow INSTALL.md steps first".

biodranik (Migrated from github.com) reviewed 2021-11-14 21:55:00 +00:00

docs/INSTALL.md

					
				@ -7,0 +29,4 @@

				git clone https://github.com/<your-github-name>/organicmaps.git

				```

				Add a `--filter=blob:limit=128k` option to above command to make a _partial clone_ of just ~1.2Gb, i.e. blob files over 128k in size will be excluded form the history and downloaded on-demand - should be suitable for a generic development use.

biodranik (Migrated from github.com) commented

2021-11-14 21:55:00 +00:00

Why 30+ GB? My full checked-out repo takes ~9GB (7GB .git folder). Every Android arch debug build takes an additional 4.5Gb. Building a desktop-only app takes also a few GBs, depending on the configuration.

biodranik (Migrated from github.com) reviewed 2021-11-14 21:58:48 +00:00

docs/INSTALL.md

biodranik (Migrated from github.com) commented

2021-11-14 21:58:48 +00:00

Also adding default desktop target can help people.

Also adding default `desktop` target can help people.

pastk reviewed 2021-11-15 07:23:28 +00:00

docs/INSTALL.md

					
				@ -7,0 +29,4 @@

				git clone https://github.com/<your-github-name>/organicmaps.git

				```

				Add a `--filter=blob:limit=128k` option to above command to make a _partial clone_ of just ~1.2Gb, i.e. blob files over 128k in size will be excluded form the history and downloaded on-demand - should be suitable for a generic development use.

pastk commented

2021-11-15 07:23:28 +00:00

30+Gb is a minimum total that also includes android studio, sdk, ndk, etc.

On my system it looks like this:

  1.6 android studio
  8.5 full repo
  9 sdk, ndk, emulator image
  1.5 ~/.android/avd (emulated storage etc?)
  = 20.5Gb
  
  +1.5 ~./gradle/caches
  +4.5*3=13.5 build files for 3 arches
  = 35.5Gb total

There I have a small emulator image without Google services and a quite old low-mem emulated device (Nexus S) and just a 256Mb emulated SD. With a more conventional option it'll be a couple Gb more.

So actually if we expect someone to just follow default instructions and build for all 3 arches (which is by default) then it comes close to 40Gb...

30+Gb is a minimum total that also includes android studio, sdk, ndk, etc. On my system it looks like this: > 1.6 android studio > 8.5 full repo > 9 sdk, ndk, emulator image > 1.5 ~/.android/avd (emulated storage etc?) > = 20.5Gb > > +1.5 ~./gradle/caches > +4.5*3=13.5 build files for 3 arches > = 35.5Gb total There I have a small emulator image without Google services and a quite old low-mem emulated device (Nexus S) and just a 256Mb emulated SD. With a more conventional option it'll be a couple Gb more. So actually if we expect someone to just follow default instructions and build for all 3 arches (which is by default) then it comes close to 40Gb...

pastk reviewed 2021-11-15 07:26:51 +00:00

docs/INSTALL.md

					
				@ -7,0 +31,4 @@

				Add a `--filter=blob:limit=128k` option to above command to make a _partial clone_ of just ~1.2Gb, i.e. blob files over 128k in size will be excluded form the history and downloaded on-demand - should be suitable for a generic development use.

				And/or add a `--depth=1` option to make a _shallow copy_ (and possibly a `--no-single-branch` to have all branches not just `master`), i.e. omit history retaining current commits only - suitable for one-off builds.

pastk commented

2021-11-15 07:26:51 +00:00

Yeap I agree it should be simple and newbie-friendly.
I'll try to re-arrange!

Yeap I agree it should be simple and newbie-friendly. I'll try to re-arrange!

pastk reviewed 2021-11-15 07:39:00 +00:00

docs/INSTALL.md

pastk commented

2021-11-15 07:39:00 +00:00

Thanks! I'll do it in next PR, my idea was to limit the current PR to deduplication and update of the Getting sources section.

biodranik (Migrated from github.com) reviewed 2021-11-15 10:28:26 +00:00

docs/INSTALL.md

					
				@ -7,0 +29,4 @@

				git clone https://github.com/<your-github-name>/organicmaps.git

				```

				Add a `--filter=blob:limit=128k` option to above command to make a _partial clone_ of just ~1.2Gb, i.e. blob files over 128k in size will be excluded form the history and downloaded on-demand - should be suitable for a generic development use.

biodranik (Migrated from github.com) commented

2021-11-15 10:28:25 +00:00

Interesting. We probably need to document a "low space" options, e.g. installing only JDK without Android Studio (or reusing a system one), building release instead of debug to save some space, mounting a compressed NDK image :)

But let's start focusing on systems with enough free space first and make it an easy start for these environments.

Interesting. We probably need to document a "low space" options, e.g. installing only JDK without Android Studio (or reusing a system one), building release instead of debug to save some space, mounting a compressed NDK image :) But let's start focusing on systems with enough free space first and make it an easy start for these environments.

biodranik commented

2021-11-16 22:51:22 +00:00

(Migrated from github.com)

We can merge it as is, the doc is already better than before.

biodranik (Migrated from github.com) approved these changes 2021-11-16 22:51:32 +00:00

pastk commented

2021-11-17 07:37:55 +00:00

We can merge it as is, the doc is already better than before.

Ok great, thanks!
And I'll continue re-arranging and improving from there as discussed above!

(please don't mind I'm quite slow with updates atm - have limited time - but I'm commited to continue to improve the docs)

Upd: a follow-up WIP PR organicmaps/organicmaps#1568

> We can merge it as is, the doc is already better than before. Ok great, thanks! And I'll continue re-arranging and improving from there as discussed above! (please don't mind I'm quite slow with updates atm - have limited time - but I'm commited to continue to improve the docs) Upd: a follow-up WIP PR https://git.omaps.dev/organicmaps/organicmaps/pulls/1568

This repo is archived. You cannot comment on pull requests.

No reviewers

biodranik