Contributing to the IDE

[Monte Goulding]

Hmm… OK Geoff, sorry for being flippant and causing a rant!

I must admit I don’t know anything about GitKracken. I used to use SourceTree which I found quite reasonable, however, once working for the LC team I found it too slow and hard to do some of the more complicated things like interactive rebasing so I moved to command line.

> None of it comes close to describing the steps necessary to set up on my computer to contribute.

The issue I think you are bumping in to is you only really want to contribute to the IDE, however, to do so you really need to build livecode from source so you can work on the IDE directly in the respository. Because of that the notes linked in the README.md about building LC on different platforms under the section `Detailed instructions` are really what you are looking for. https://github.com/livecode/livecode#detailed-instructions <https://github.com/livecode/livecode#detailed-instructions>
> 
> it offers nothing useful to figuring out how to set up to contribute.

Yes it does. See above ^.
> 
> I ran into this same problem when I started to put Navigator into GitHub: the GitHub documentation is absolutely abysmal. In that instance, the blame lies with literally everyone associated with Git and GitHub, but in the case of wanting to contribute to the LC IDE, the buck stops with the LC crew. I have asked others who are decades-long LC developers for guidance, and found that they don't understand how to contribute. That holds back development of LC and the IDE.

OK, well we’d like to do better in this regard, however, we do tend to run into the problem that a large chunk of our experienced LC developers have no interest in reading about git or github. The very best thing you can do before anything else is understand git. There is bucket loads of freely available information online. This is a great free book https://git-scm.com/book/en/v2 <https://git-scm.com/book/en/v2>
> 
> To be clear: reasonable documentation for contributing to the IDE would include a section something like:
> 
> 1. Create an account on GitHub. Follow the guidelines mentioned elsewhere in this documentation.

OK, this has presumably been seen as assumed knowledge til now… and/or GitHub’s responsibility do document how to use GitHub. I’m sure we can add something though!

> 2. (optional) Install the graphic Git client of your choice (a list of possibilities is included at the bottom of this documentation).

The problem here is there are lots of graphic git clients. All look different. Ali has spent quite some time documenting how to contribute via GitHub’s web interface.

> 3. Determine which version of LC you want to contribute to. Note that only contributions to <version list> are being accepted at present.

See https://github.com/livecode/livecode/blob/develop/CONTRIBUTING.md#branches-in-github <https://github.com/livecode/livecode/blob/develop/CONTRIBUTING.md#branches-in-github>
> 4. Clone the repository for the LC version you have selected to your local drive.

Yes, I agree there’s some missing bits here on forking on github, cloning and setting up the clone. I can give command line instructions and or write a script for you to run.

Basically we use multiple repositories to build LiveCode. Ignoring the commercial repositories that only the team have access to the structure is:

livecode
   ide -> livecode-ide
   thirdparty -> livecode-thirdparty

Most of the ide stacks are in the livecode-ide repository, however, there are some in the ide-support folder of the livecode repository and we are gradually moving as many modular libraries as possible to the extensions/script-libraries folder of the livecode repository.

The thirdparty repository is something that anyone outside the team is unlikely to need to patch so we can ignore that for now.

So to work on the ide you really need to fork both https://github.com/livecode/livecode <https://github.com/livecode/livecode> and https://github.com/livecode/livecode-ide <https://github.com/livecode/livecode-ide>

From there you need to do the equivalent of the following in your git client:

git clone —recursive https://github.com/<yourgithubusername>/livecode.git <https://github.com/%3Cyourgithubusername%3E/livecode.git>

This is basically downloading the source folder and it’s history into a folder named livecode.

Once that is complete then there are a few changes to make to get setup:

cd livecode
git remote add upstream https://github.com/livecode/livecode.git <https://github.com/livecode/livecode.git>
cd ide
git remote rename origin upstream
git remote add origin https://github.com/<yourgithubusername>/livecode.git <https://github.com/%3Cyourgithubusername%3E/livecode.git><yourgithubusername> <https://github.com/%3Cyourgithubusername%3E/livecode.git>/livecode.git

Now you are ready to follow the configure and build instructions for your platform. If you are on mac you can build and run directly from Xcode, edit IDE stacks, save them and then make the patch via git.

> Save it to your Applications folder.

No… don’t do that… My clone is in my home folder… you can clone just somewhere it’s easy to work on.

> Do not overwrite your working copy of LiveCode.

Definitely don’t do that ;-)

> 5. You will need to follow these additional steps to make that repository functional:

If we are considering just IDE development then this step is probably building LC although see https://github.com/livecode/livecode#detailed-instructions <https://github.com/livecode/livecode#detailed-instructions> for your platform to work out the extra things that need to be installed on your system to build.

> 6. License the copy of LC included in the repository.

No need to do that as it’s community

> 7. Make whatever changes to the IDE you wish. Note that you must segment your changes in individual branches; if you lump a large number of changes in one branch, your updates will almost certainly be rejected.

See https://github.com/livecode/livecode/blob/develop/CONTRIBUTING.md#creating-a-pull-request <https://github.com/livecode/livecode/blob/develop/CONTRIBUTING.md#creating-a-pull-request>
> 8. When you have a branch ready to merge into the production copy of LiveCode, issue a pull request. Please follow the documentation descriptions listed below; if we can't understand your change, it will be rejected.
> 
> To be more clear, I have no idea if the above is the correct sequence of steps. That's the problem I'm trying to solve, and neither of the referenced documents, nor any admonishment to study them in greater detail, will solve it.

OK, point taken. If we can work out all the points that people feel are missing we would love for more people to be able to contribute. BTW here is a video I did for someone about using sourcetree which may or may not shed some light. https://www.youtube.com/watch?v=W14_fiRA6Wo&t=847s <https://www.youtube.com/watch?v=W14_fiRA6Wo&t=847s>

Cheers

Monte