Repository on github

[Alistair Ward]

Following the discussions with Martin re version control, I have gone ahead and created a public repository on github for Templot3.

The link is: https://github.com/alistair-ward/templot3

So far I haven't done much beyond basic setup. I've now set up so I can build Windows 32- and 64-bit using Lazarus/FPC. I'm using the current versions of Lazarus 2.0.10 and FPC 3.2.0 I hope to get it building on a Raspberry Pi as well, but still working out how to get the latest version of Lazarus and FPC on there.

I've decided that my first efforts will go into fixing up compiler warnings across platforms. I've made one significant commit so far, which is to use a dynamic array for the Tmark's. This is a first step towards 64-bit compatibility...

As and when I have time, I'll look at replacing other uses of the intarrary code with dynamic arrays as appropriate.

Cheers,
Alistair

 

[Martin Wynne]

Hi Alistair,

Many thanks for doing that. I need to learn my way around in Github, it's a bit different from SourceForge.

I'll look at replacing other uses of the intarrary code with dynamic arrays as appropriate.

I will be interested to see how that works out. The coal-fired intarray stuff has been working totally unchanged for over 20 years without any problems whatsoever. Which is a good reason to keep it, and a good reason to replace it with something more up-to-date.

Are you intending to create separate 32-bit and 64-bit versions of Templot3?

cheers,

Martin.

 

[Alistair Ward]

Hi Martin,

Yes I'm intending to be able to build Templot as either 32- or 64-bit.

Cheers,
Alistair.

 

[Martin Wynne]

@Alistair Ward @graeme

Hi Alistair, Graeme,

I have decided not to delete my account on SourceForge. But it needs a link to your GitHub repository for the up-to-date developments:

https://github.com/alistair-ward/templot3

Is that the correct public link? Is it ok to post it on SourceForge? Is this the actual T3 project, or a fork from it? Does Graeme have an alternative GitHub site of his own? Is there any other T3 link I should know about? Where should someone wanting to get into T3 now start from? Sorry to be a bit dumb.

I see that SourceForge have an automated GltHub integration function, so that anything on GitHub can be automatically copied to SourceForge. Is that something we might want to set up?

My main reason for deciding to continue with my SourceForge account is so that I have somewhere to post the Templot2 installer which will last forever, or until T3 is ready to replace it. See:

https://85a.uk/templot/club/index.php?threads/templot-forever.204/

SourceForge link:

https://sourceforge.net/projects/opentemplot/

cheers,

Martin.

 

[graeme]

Hi Martin,

https://github.com/alistair-ward/templot3

Is that the correct public link?

No, we have a separate "user" under which the 'master' copy is kept. (In github terminology it is an 'organisation'.)
The link is https://github.com/openTemplot/templot3
This enables Alistair and I to BOTH have our own personal forks, neither of which have any special privileges. We are just two contributing developers, the same as anyone else who may joins us.

{-{ Incidentally, the term 'master' is a slightly odd one to use, since git is a completely peer-to-peer system, meaning that every copy of the reository is as good as any other copy. The only concept of master is the one we impose on it and the one granted to it by github as the root of a tree of forks. }-}

Is it ok to post it on SourceForge?

Absolutely!

Is this the actual T3 project, or a fork from it?

The link given above is the 'root', if you like. It is not forked from anything, and all others are forked from it (or from forks of it ).

Does Graeme have an alternative GitHub site of his own?

Yes, analogous to Alistair's, there is https://github.com/alistair-ward/templot3, but that is my private fork. It is unlikely that anyone will be interested in it unless they want to take a look at some work-in-progress that has not been merged into the "master".

Is there any other T3 link I should know about?

Probably not really of general interest, but the 'organisation' has another repository where I am storing all the T1 files that you post. That is not really for public consumption, but rather a centralised store that we can use for diff-ing as we go forward. It has the catchy and rather imaginative name of templot1 It's home is https://github.com/openTemplot/templot1

Where should someone wanting to get into T3 now start from?

https://github.com/openTemplot/templot3 is the place to go, although there are no notes for beginners on how to get started yet.
( @alistair-ward do we perhaps we need a 'getting started' section in the readme? )

Sorry to be a bit dumb.

Not at all. There are a number of moving parts and it does take a while to get the picture clear.

I see that SourceForge have an automated GltHub integration function, so that anything on GitHub can be automatically copied to SourceForge. Is that something we might want to set up?

As I understand it that facility creates (and synchronises) a copy of the github repo on SF. How it works when someone with such a copy wants to contribute changes to the project, I am not sure, but I assume there is a way.
Personally I find the SF site a bit cluttered and awkward to navigate, but i am sure that is just my lack of familiarity. For anyone who prefers to work on SF this integration would perhaps be a good idea.

My main reason for deciding to continue with my SourceForge account is so that I have somewhere to post the Templot2 installer .......

Yes, indeed!

Cheers,

Graeme

 

[Martin Wynne]

Yes, analogous to Alistair's, there is https://github.com/alistair-ward/templot3, but that is my private fork.

@graeme

Thanks Graeme, but I think you forgot to edit that URL.

Also,

It's home is https://github.com/openTemplot/templot1

is giving me a 404 not found error, and searching for templot1 on there comes up with no results?

The link is https://github.com/openTemplot/templot3

Who actually owns that page and writes the text?

I confess I find the whole thing too confusing for words.

I shall continue to post the T1 files here on Templot Club, and look forward to the day when I can make some sense of it all.

p.s. the above pages refer to http://templot.com Although that domain still works (and should continue to work), there is no https certificate on there -- the "official" URL is now https://85a.uk/templot/

cheers,

Martin.

 

[graeme]

Thanks Graeme, but I think you forgot to edit that URL.

Yes, indeed. My apologies. It should of course have been https://github.com/graeme-defty/templot3

... searching for templot1 on there comes up with no results?

When a new repo is created it is set up as 'Private', meaning nobody can see it but the owner.
I did not originally think the templot1 repository would be of interest to anyone but Alistair and myself (and perhaps any other developers who joined in) so I left it as private, since the files are available on the Templot site.

However I can certainly make it a public repository if you prefer. Just let me know.

Who actually owns that page and writes the text?

What I have referred to as the 'master' repository is 'owned' by a kind of virtual github user called "openTemplot" that I set up for the purpose. In github terms this is called an 'organisation', and the sole purpose of this one is to be the owner of this 'master' repository.

Github allows for a small number of people to be what are known as 'members' of the organisation. These members are responsible for the care of the repository.

For the moment only Alistair and I are members of the organisation. Of course we can add others, but the number is generally kept small.

That source itself is never written to directly by anyone - including the members of the organisation. First a developer has to create a fork (as Alistair and I have already done). This is their own private copy of the repository. This is a complete and autonomous copy, but github remembers where it was forked from, as you can see from the top-left corner of the screen for my fork:

If you click on the "forked from" link, it will take you to the original or 'organisation' repo, and you will notice when you get there that there is NO "forked from" link - that repo is the basis from which everything else forks.

The developer then works only in their own repo.

If they make some changes which they want to contribute to the project, then they raise what is known as a 'Pull Request' (which is done by simply clicking a button on github.)

The request is flagged up to the organisation, and if the members are happy with the change, then it is pulled into the 'master' repo.

Note that nobody pushes changes to the master. They are always pulled, thus maintaining control over the integrity of the contents.

This is no different from me sending you a possible change for T2 and you deciding whether or not you wanted to include it in the program.

I confess I find the whole thing too confusing for words.

Well, I hope this has helped a little, though this is not a great place to try and craft a tutorial, so I fear that I may have done more harm than good.

I shall continue to post the T1 files here on Templot Club, and look forward to the day when I can make some sense of it all.

It will come. I confess it took me a little time to get both my brain cells awake at the same time to really 'get' all of this.

p.s. the above pages refer to http://templot.com Although that domain still works (and should continue to work), there is no https certificate on there -- the "official" URL is now https://85a.uk/templot/

Ooops! I will fix it right now.

Cheers,

Graeme

 

[Martin Wynne]

@graeme

Thanks Graeme.

That source itself is never written to directly by anyone - including the members of the organisation.

But below and alongside the list of files there are sections of text explaining the project. Someone must have written that, and be in a position to edit it?

I confess it took me a little time to get both my brain cells awake at the same time to really 'get' all of this.

What I'm finding such a muddle is that there are numerous versions of each file in different places, all with the same name. How on Earth does anyone approaching the project know which one to use or refer to? Or which one the others are discussing?

What I would have expected is that there is one file called abc_unit.pas online, and discussions between contributors would be about individual chunks of code of say a few dozen lines, and how best to implement some change or feature. And when all are agreed, that chunk of code would be inserted into the one file.

For the present I'm going to leave it to you and Alistair to know what you are doing, while I continue to work on Templot2 in Delphi and post the files as T1.

I have added the GitHub link to the front page on SourceForge at: https://sourceforge.net/projects/opentemplot/

cheers,

Martin.

 

[graeme]

But below and alongside the list of files there are sections of text explaining the project. Someone must have written that, and be in a position to edit it?

Oh crumbs, sorry, Martin - I misunderstood completely.

The text below the project file list is just the README.md file in the root of the project. No different from any other file. Alistair contributed most (in fact I think all) of the current version. It is in Markdown format (hence the '.md') which is just a way of formatting (headers, lists, etc) in a readable way. If you are not familiar with it, the examples on the wikipedia page are probably as clear an explanation as you will find. https://en.wikipedia.org/wiki/Markdown - scroll down to the table.

The text to the right of the page is an attribute of the project that github holds. It is not actually IN the project. I penned that particular piece.

What I'm finding such a muddle is that there are numerous versions of each file in different places, all with the same name. How on Earth does anyone approaching the project know which one to use or refer to? Or which one the others are discussing?

What I would have expected is that there is one file called abc_unit.pas online, and discussions between contributors would be about individual chunks of code of say a few dozen lines, and how best to implement some change or feature. And when all are agreed, that chunk of code would be inserted into the one file.

Hmmm - this is not easy to explain without some background in git, but let me try to shed a little light...

The question of what a newcomer does IS easy. They go to the master copy at https://github.com/openTemplot/templot3. Working from this base will allow them to make pull requests sometime down the track.

Of course, if they don't want to feed their changes back to the project, that's fine too. It is not unusual to see people simply taking a copy of the source and going their own sweet way with it.

With regard to discussions, and indeed changes, they take place pretty much as you have described. I think one of the key ideas here is that although each developer has their own copy of the source, the truth is it rarely deviates all that much from the master copy.

After making a change, a developer will first 'pull' any recent changes from the master. This brings in any recent contributions from others into the developer's copy, so their copy is now up to date with the master, but also contains their new code, built on top of that current master. Now they are in a position to make a pull request, and that pull request, once accepted, brings their changes into the master. In a sense it re-aligns the master copy with their copy. The two are now the same.

As to actually merging the changes together, this is the job of git. Truly this would all be durned near impossible without it, or something very much like it.

I have added the GitHub link to the front page on SourceForge at: https://sourceforge.net/projects/opentemplot/

OK - thanks.

Cheers,

Graeme

 

[Martin Wynne]

After making a change, a developer will first 'pull' any recent changes. This brings in any recent contributions from others into their copy, so their copy is up to date with the master, but also contains their new code, built on top of that current master. Now they are in a position to make a pull request, and that pull request, once accepted, brings their changes into the master. In a sense it re-aligns the master copy with their copy. The two are now the same.

As to actually merging the changes together, this is the job of git. Truly this would all be durned near impossible without it, or something very much like it.

@graeme

Hi Graeme,

Thanks for trying to explain it, but I'm afraid I'm obviously missing something.

I can't imagine how I could be working on some code in a file, while knowing that someone else might be working on the same file at the same time, and possibly making changes which would conflict with mine.

What I would have expected is that contributors would work on a specific feature, rather than an existing file. So for example someone might decide to implement a function to add OLE mast positions alongside the track. Having got some code working for that, they might then discuss it with the others about whether it is wanted, and which file it should go in, or maybe in a new file if it requires its own form. And what changes it will require in other files, such as new menu entries elsewhere. Anyone working on anything which might conflict with it would be able to say so. And only when all is agreed, would the changes be inserted into the one and only set of master files online.

If on the other hand someone wanted to fork from the master files and do their own thing, that would create a completely different project, and the two projects would never meet again. Some code chunks might be swapped between the contributors, but not whole files within the projects.

However, I'm going to leave you to it, and get on with Templot2 in Delphi, where I know what I'm doing.

cheers,

Martin.