Update readme
The readme currently refers to sourceforge and likely needs updating in other places as well.
Comments (14)
-
-
Personally I think the first option is the better approach.
The bit you've got in bold can be explained as follows:
- The sub-module information stored in GS2 can be thought of as a pointer to a particular commit in utils and Makefiles.
- This pointer is part of the repository history
- 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).
- 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).
- We have to commit this change to the GS2 repository and push it if we want to share it with all.
-
I am just writing some text about how to do this practically
-
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://colinmroach@bitbucket.org/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!:
- developer who wants to be able to push back updates including to "utils" and "Makefiles"
- 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!
-
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.
-
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.
-
PR #19 contains these changes, the text starts at https://bitbucket.org/gyrokinetics/gs2/pull-requests/19/contributing-docs/diff#LCONTRIBUTING.mdT233
-
I just tried
git clone --recurse-submodules https://colinmroach@bitbucket.org/gyrokinetics/gs2.git
-
Currently that probably won't do what we want as the sub-module stuff is not in master yet.
-
it did NOT produce Makefiles or utils below gs2. This was unexpected.
-
@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!
-
@colinmroach @ZedThree @daviddickinson Are we (relatively) happy with the state of the README? Was this issue resolved by PR #19?
-
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. -
- changed status to resolved
See issue
#59for discussion - Log in to comment
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
orMakefiles
will either have to:clone a separate copy of
utils
andMakefiles
via the git protocol, make changes to those, push those changes and then pull them into theirgs2
working copy; oradd
git config --global url.git@bitbucket.org:gyrokinetics/
instead ofhttps://bitbucket.org/gyrokinetics/
to their git configuration before cloninggs2
, thus allowing them to make and push changes directly from theutils
andMakefiles
subdirectories within theirgs2
working copy. However, the updated submodules need to be registered with thegs2
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*