search

Ixox / preenfm3

Official repo of the preenfm3 FM synth
107 stars 23 forks source link

avoid wiki docs #4

Open axd1967 opened 3 years ago

axd1967 commented 3 years ago

This is a good step forward and please continue this way.

There is one issue that I would urge to change: avoid the wiki. Wikis look attractive (especially their menu system) but they have a major problem: they cannot be kept in sync with branches/code changes, because they are separate repositories. (And I'm more and more inclined to think that this is a fundamental issue with wikis on GitHub.)

Wiki-like pages can just as well be created in (e.g.) a wiki/ folder under https://github.com/Ixox/preenfm3. this will allow to keep "wiki" pages and code in sync, because changes in firmware will sometimes impose changes in wiki pages, but because the commit/release cycles are different, there will be a need to keep wiki and code somehow in line during such transitions. branches are the natural way to deal with this: in a branch, code and wiki pages are updated at the same time, and this tight linking provides an additional bit of documentaiton. Also, this allows anyone that tracks the code to also detect changes in the wiki, and it bundles really all project information in one single repository that can easily be cloned.

Admitted, the wiki provides nice menus, that a normal page won't (but you can also benefit from markup in normal pages, e.g. by using .rst an an example).

See also https://github.com/Ixox/preenfm2/issues/1

(I'm not sure about https://github.com/Ixox/preenfm2Controller - I'm tempted to think that the system and the editor are tightly linked, so they should live in the same repo. in other words: can the editor live a life without the synth? I don't think so. the synth could do without the editor, but is that a reason to split off the editor? I don't think so).

Ixox commented 3 years ago

Thanks that's interesting. Will think about that.

axd1967 commented 3 years ago

If you think of it, preenfm3 is just an evolution of preenfm2 which is an evolution of preenfm. This is VCS parlance for "versions".

This can all be managed from a single repo.

Every new model starts off the latest branch of a previous model as a development branch (eg model/3/idea, model/3/dev) and is finally merged to a "master" (model/3/maintenance) and tagged (eg v/2/2.08, v/2/2.20.b2, v/3/0.1, v/3/0.94, ...)

Note the use of slashes to further increase the organisation of the tag namespace and avoid all tags ending up in a single tag namespace "soup" . This can then also be admired from the CLI:

alex@xray:/tmp/preenfm3$ tree .git

.git
├── branches
├── config
├── description
├── FETCH_HEAD
├── gitk.cache
├── HEAD
├── hooks
│   ├── applypatch-msg.sample
│   ├── commit-msg.sample
│   ├── fsmonitor-watchman.sample
│   ├── post-update.sample
│   ├── pre-applypatch.sample
│   ├── pre-commit.sample
│   ├── pre-merge-commit.sample
│   ├── prepare-commit-msg.sample
│   ├── pre-push.sample
│   ├── pre-rebase.sample
│   ├── pre-receive.sample
│   └── update.sample
├── index
├── info
│   └── exclude
├── logs
│   ├── HEAD
│   └── refs
│       ├── heads
│       │   ├── master
│       │   └── model
│       │       ├── 3
│       │       │   └── maintenance
│       │       └── 4
│       │           └── dev
│       └── remotes
│           └── lxox
│               ├── Fdbk
│               ├── HEAD
│               ├── master
│               └── v094
├── objects

...
│   ├── info
│   └── pack
│       ├── pack-1fc59af7d14e7bfbe09e81c3f220f8514c556913.idx
│       └── pack-1fc59af7d14e7bfbe09e81c3f220f8514c556913.pack
├── ORIG_HEAD
├── packed-refs
└── refs
    ├── heads
    │   ├── master
    │   └── model
    │       ├── 3
    │       │   └── maintenance
    │       └── 4
    │           └── dev
    ├── remotes
    │   ├── lxox
    │   │   ├── Fdbk
    │   │   ├── HEAD
    │   │   ├── master
    │   │   └── v094
    │   └── origin
    └── tags
        └── v
            └── 3
                ├── 0.90
                ├── 0.93
                ├── 0.94
                ├── 1.0
                └── 1.0.1

55 directories, 73 files

master can become the development branch of the latest model but I would ditch master and use model/N/dev and model/N/maintenance; earlier, released models just receive maintenance branches (model/N/maintenance) to fix issues.

* c31668a (HEAD -> master, model/4/dev) release model 4
* 6356042 prepare for release
* e13683b continue R&D
*   4563fcf Merge branch 'model/3/dev'
|\  
| * 382dbea more work
| * 273eb86 more work
| * 6a155e5 test
| | * 884ae7d (tag: v/3/1.0.1, model/3/maintenance) bugfix for model 3
| |/  
|/|   
* | 0fcdbf0 (tag: v/3/1.0) final!
* | c78e67f bugfix
* | f15655d (tag: v0.94, tag: v/3/0.94, lxox/master, lxox/HEAD) Remove Debug info from Release
* | af9ff15 Merge pull request #5 from Ixox/v094
|\| 
| * ac59d07 (lxox/v094) Fix buton state bug (Crash)
| * c5db765 Multiple edition show up in green
| * 86f4438 Multiple param edition : EDIT + encoder turn
| * 49b342b v0.94 first commit
| * 2df6b30 Modification to use last lib
| * dff063d Small display optimization and stability
| * 4233930 Control board v1.1
|/  
* c086304 (tag: v0.93, tag: v/3/0.93) Bootlader 1.03 TFT fixed
* 0621950 Slower and much more stable UI with some TFTs
* c496182 Fix quick start doc
* 7cb2100 doc/README added
* 1405230 Add quick start pdf doc
* 04bc544 (tag: v0.92) Tiny type fix
* 26a9d33 Limit SD SPI to 12.5Mhz (will use actually 7.5Mhz)
* c815cb4 Bootloader 1.02 : use button 1,2,3
* c0ab974 Create object use _ in bin names
* bb52e92 No more DEBUG preprocessing in Release
* 9d41875 Better Seq presentation
* 412e46b Fix seq cursor refresh bug
* 251d024 Sequencer has its own default file
* dc86de4 Sequence V2 bug fix
* 5276057 Sequencer V2 + many small fixes
* 8a0f6af update version.h
* eb0416d Add colors after reinit TFT
* b9349bf Faster encoder polling
* dce21d6 3DCaseB added
* eaef23f (tag: v0.91) Allow -O3 on preenfm3_lib
* 6850231 Bootloader fixed : SD access don't use DMA
*   4510205 Merge pull request #2 from Ixox/Fdbk

a bit simplified:

image

As you can see, I use gitk... The power of Git is in the concepts.

Some Git clients can represent tags and branches in a nice tree (which then allows to collapse unneeded sections), that's an additional reason to use slashes in those names.

Consider this approach for version 4 onwards? This will unify all future work of all preenFM knowledge in a single repo.

Ixox commented 3 years ago

Thanks a lot for the detailed message. If one day i have more free time, i'll change many things (better git management is one of those ;) ).

axd1967 commented 3 years ago

Don't worry - this is a slow but steady process, you are on the right track.

axd1967 commented 3 years ago

GitHub page sites add a new dimension in that you can replace a site with GitHub Markdown pages.

With the added advantage that everything is finally managed from a single Git repository. which further eases opening the project (https://github.com/Ixox/preenfm2/issues/1) and sharing with everybody.

here you see some examples of such GitHub pages:

More info here: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#publishing-sources-for-github-pages-sites