Repo Status/Plans for 2.0

[bpalmintier]

As part of final 2.0 release prep, let's finalize the plans for all of our repositories. Right now we have archived one repo, and I think we likely want to keep most/all of the others, but wanted to do so intentionally, rather than by default. In addition I think we should clean up a few items, including adding notes to any repos we keep active, but that use v1.3. See the list and notes in the table below

Thoughts?

Repo	Status	Proposal and Notes
Core HELICS
HELICS
helics-cli
homebrew-helics		archived
Documentation
HELICS-Examples
HELICS-Use-Cases		Add note that many using older version
HELICS-User_Guide		archived as integrated with main HELICS repo
HELICS-Tutorial		Harmonize with User Guide?
Interfaces
PSLF-wrapper		Add helics to name?
MATPOWER-wrapper		Add helics to name?
HELICS-FMI		up to date
containers		up to date
helics-ns3
HELICS-HLA		Add note about using older version
ns-3-dev-git	Archive	Archived

[bpalmintier]

PS: While we are at it, do we want to pick a standard capitalization for HELICS (vs. helics) in the repo names?

[trevorhardy]

Right now, the definitive version of the User Guide is in the "HELICS-src" repo ("docs") folder. I think I have a slight preference to keep it there and link to it visibly from other documentation webpages rather than having a stand-alone repository. In theory, as we make changes to HELICS-src the examples in the User Guide could be run automatically to continuously confirm the validity of the User Guide. More generally, we need some way of at least knowing when the documentation (examples, User Guide, etc) is out of date and I guess I'm hoping having it in the main repo will motivate us to do that. If there's a better mechanism I'm open to it.

All of the use cases in the "Use Cases" repo were developed under v1.3 (or earlier) and likely none of them work under v2.0.

I haven't spent any time in the "Tutorial" or "Examples" folders. I know "HELICS-src" has an examples folder but I don't know how it differs from what is in this repo. The "Examples" repo looks to have API call examples that hasn't been touched since early Oct 2018. I think having these examples is very useful but it would clearly need to be updated for v2.0. Again, maybe they can be merged into "HELICS-src" alongside the User Guide.

[bpalmintier]

One big reason to consider pulling out the User Guide from the src is that many user guide users would likely be using per-compiled binaries for HELICS, while we might want to point them to the user guide repository for the user guide, especially if we maintain any example data and code along with it. It seems excessive for them to wade through the HELICS-src just to work through things this way.

In general, we had been trending toward having a modest number of more manageably sized and targeted repositories, rather than trying to put everything into one giant behemoth. This is partially a git vs. svn difference, since git naturally grabs the entire repo (& history) when cloned, but more generally, also allows capabilities like tools, examples, etc. to be updated without forcing an update to the version number for HELICS (and without holding up their general release for such a version number, as has happened with some tools). @kdheepak would love to hear your thoughts on this one giant vs multiple small repo trade-off.

On the two example folders: agree we could use more clarity, but for many of the same reasons, I'd lean toward keeping the current API examples separate. Again they have a valid standalone use without everyone having to work or check-out the full source code. More importantly for these users, we don't want them making minor one-off user-specific changes to the core HELICS source code (we'd rather them use the standard releases and contribute any updates to the community). Keeping this repo separate should help encourage this distinction. (Note: I think there is a 2.0 branch for these external examples.) Do we still want the HELICS-src examples at all? What purpose do they serve beyond the tests and external examples? Perhaps we could rename if we keep.

The Tutorial folder was basically a first cut at something I believe the User guide is now doing: covering a domain-specific example with tools and data to understand how HELICS works. That original version didn't have the same narrative and documentation as the user guide, but since it served much the same purpose should likely be harmonized, possibly by Archiving it in leu of the new User guide.

[nightlark]

The examples in HELICS-src are just there as small compilation tests. The different repo was to better show how linking projects to HELICS works (the examples folder in HELICS-src links in a way that is not possible for actual users using CMake), and to separate testing concerns. The Examples repo has a 2.0 branch. Ideally, things would be setup to trigger builds in the Examples repo when HELICS builds successfully, similar to the HELICS-FMI and helics-ns3 repos.

[bpalmintier]

(Note: comment opening line updated to clarify tutorial vs. user guide) might be best to view this thread on line.

[bpalmintier]

@nightlark-- thanks for the clarificationon HELICS-src examples. Might we rename that folder to compile-test or the like to clarify?

[nightlark]

@bpalmintier something like that should be okay. For capitalization, it seems all lowercase names is typical for ns-3 module names/folders -- but there are some changes in a current ns-3 PR that will make module structure/names more flexible.

[trevorhardy]

@bpalmintier, good point about users not necessarily downloading source; I'm in favor of moving them out. There will be some shuffling and juggling to get the right files in the right places but the effort should be minimal.

[phlptp]

I think a compiled version of the user-guide should be included in the install package, a PDF of it of some sort. If we were to do that it would be required to have that be built along side the rest of HELICS so it is available in the same source location.

[phlptp]

I think leaving it as examples is useful just to a have a small example set be available with the source code. Like @nightlark said the ones we left were for a couple compile tests to ensure they get updated with the code and there are no obvious linking issues.

[phlptp]

there probably should be a support category in the above list. Right now the only thing that goes into it is the containers repo, but if that proves workable and useful we might break out a few more pieces into separate repos which would also fall into that category.

[phlptp]

I think this issue is out of date and most of what we were using it to track has been done, so I am going to close it and open a few issues on some of the repos that have not been completely dealt with yet.