Update readme

[Former user]

The readme currently refers to sourceforge and likely needs updating in other places as well.

[Colin Malcolm Roach]

README discussion of how to deal with utils and Makefiles is quite confusing. The second way to handle commits to these parts of the code sounds like the easier approach, but what does the sentence in bold actually mean, and could it be expressed more clearly?

*Furthermore, the default protocol of the submodules is HTTPS. This is necessary to enable GS2 users (non-developers) to download the code successfully. Therefore, developers who wish to modify code belonging to utils or Makefiles will either have to:

• clone a separate copy of utils and Makefiles via the git protocol, make changes to those, push those changes and then pull them into their gs2 working copy; or

• add git config --global [e-mail]:gyrokinetics/ instead of https://bitbucket.org/gyrokinetics/ to their git configuration before cloning gs2, thus allowing them to make and push changes directly from the utils and Makefiles subdirectories within their gs2 working copy. However, the updated submodules need to be registered with the gs2 project via commits.

See the official git documentaion e-book for further details on working with sub-modules: https://git-scm.com/book/en/v2/Git-Tools-Submodules*

[David Dickinson]

Personally I think the first option is the better approach.

The bit you've got in bold can be explained as follows:

1. The sub-module information stored in GS2 can be thought of as a pointer to a particular commit in utils and Makefiles.
2. This pointer is part of the repository history
3. If utils/Makefiles change this isn't automatically brought into GS2 as the pointer in GS2 hasn't changed (still points to the specific commit in utils/Makefiles).
4. To update the version of utils/Makefiles that is fetched into GS2 we have to update this pointer (a simple git command to fetch the specific commit).
5. We have to commit this change to the GS2 repository and push it if we want to share it with all.

[Peter Hill]

I am just writing some text about how to do this practically

[Colin Malcolm Roach]

David, please can you say why the first approach is better. It sounds slightly less complicated! 1. Concerning the first approach, if one clones a separately "utils" and "Makefiles", HOW does one then push those changes and then pull them into their gs2 working copy ? 2. What if I had previously populated "utils" and "Makefiles" using: git clone --recurse-submodules https://[e-mail]/gyrokinetics/gs2.git ? I am concerned that these steps will interfere with each other and make a mess!

I think its best if README fully describes the BEST approach for each class of user (if different approaches are needed), in a manner that assumes zero knowledege of git!:

1. developer who wants to be able to push back updates including to "utils" and "Makefiles"
2. user who only wants to read from the repository

If someone can write down the complete list of git commands for the developer on slack, and in the README I would be grateful!

[David Dickinson]

My view is that the utils and Makefiles directories in gs2 are essentially pointers specific commits in utils and Makefiles repositories -- they are not repositories. The first approach makes this clear -- if you want to work on the utils and Makefiles repositories then you just need to clone those as you would when working on any other project. It also helps make it clear that these things don't belong to GS2 but are shared.

Peter has provided (or is providing) some text to describe how to work with this.

[Colin Malcolm Roach]

OK, you obviously understand git well. We are not all so familiar!

HOW exactly does one pull any changes made to Makefiles (in the local repository) into the local gs2 working copy ? I presume these needs a number of steps:
1. update local makefile repo and send Makefiles pull request to bitbucket 2. pull request actioned 3. reassign Makefiles pointer in local gs2 repository to Makefiles repo in bitbucket? OR perhaps instead of 2,3 it is also possible to reassign the local Makefiles pointer to the local Makefiles repo (without anything going to bitbucket).

It would be useful to explicitly give the exact git commands (for those not familiar yet with git) to achieve this!

Is Peter updating the README along lines suggested above? There are many guides to using git on the web, and so the README should focus on providing gs2 users who are git newbies with the exact commands they will need to get started quickly and painlessly.

[David Dickinson]

PR #19 contains these changes, the text starts at https://bitbucket.org/gyrokinetics/gs2/pull-requests/19/contributing-docs/diff#LCONTRIBUTING.mdT233

[Colin Malcolm Roach]

I just tried

git clone --recurse-submodules https://[e-mail]/gyrokinetics/gs2.git

[David Dickinson]

Currently that probably won't do what we want as the sub-module stuff is not in master yet.

[Colin Malcolm Roach]

it did NOT produce Makefiles or utils below gs2. This was unexpected.

[David Dickinson]

@colinmroach Currently that probably won't do what we want as the sub-module stuff is not in master yet, once it is in master then it should!

[Joseph Parker]

@colinmroach @ZedThree @daviddickinson Are we (relatively) happy with the state of the README? Was this issue resolved by PR #19?

[David Dickinson]

I think the section about building the code could do with updating (for example I'm not sure how much we support build_gs2 and some of the links point to sourceforge) but it's probably OK for now.

[David Dickinson]

See issue #59 for discussion