search

embedded-graphics / examples

Embedded graphics examples
Apache License 2.0
29 stars 6 forks source link

Repository structure #9

Closed jamwaffles closed 3 years ago

jamwaffles commented 3 years ago

Continuing the discussion about how this repo should be organised, the RTIC repo uses folders like rtic_v5, etc. This seems like a reasonably clean solution to me. It doesn't require setting branches or updating links elsewhere, and it's obvious at a glance where a user might need to go for their respective versions.

It would also mean all the examples could be tested in CI if we add a top-level workspace Cargo.toml.

One downside I can see is the duplication of all the examples which might require more maintenance over time, but once a major version is released, I don't think we'd need to go back to the examples to change anything very often, if at all.

Thoughts on this structure?

rfuest commented 3 years ago

I think the branches approach is a bit cleaner, because branches exist for this very application, to keep different code versions. But if you think this would be easier to maintain and make it easier to discover the correct examples I would also be OK with this approach.

How would we handle examples for the master branch using this approach? For the branch based approach I was planning to use a git dependency to e-g for the master branch of this repo. After a new stable release the master branch in this repo would be forked into a e-g-{{version}} branch and the e-g dependency would be changed to {{version}}.

jamwaffles commented 3 years ago

I'd prefer to go with the sub-folder option if you're ok with that, for the reasons given in my original post. Right now, that pretty much just involves moving everything currently in the repo into a v6 or e-g-v6 (if we ever want to add demos for other crates here?) folder.

Each subfolder will have its own Cargo.toml which will point at the correct version. I think the development branch should be called v7 (or e-g-v7, whichever scheme we choose) and can point to either the alpha release on crates.io or just the git repo master until it's released proper.

rfuest commented 3 years ago

OK, let's use folders.

Now the complicated part... names. First of all I would suggest to include the 0. in in the directory name, because someday we might actually have a 6.0.0 release of e-g. How about eg-0.7? I've started to use the eg- prefix to abrreviate embedded-graphics- in crate names and IMO we should use the same writing everywhere. But if you have good reasons to use e-g- instead of eg- we can also still rename the crates to match.

... or e-g-v6 (if we ever want to add demos for other crates here?)

While I don't have plans to add demos that should be in another directory, I think the additional prefix keeps us flexible and doesn't make the name much longer.

I think the development branch should be called v7 (or e-g-v7, whichever scheme we choose) and can point to either the alpha release on crates.io or just the git repo master until it's released proper.

IMO we should have a eg-master directory, that will always use a git dependency. This could be tested periodically in CI to make sure the examples are always up to date with the latest master version of e-g. Examples for new features will be added in this directory first. As soon as we are near a new stable release we can copy the eg-master directory into a new directory for the next stable release and adjust the dependencies accordingly.

jamwaffles commented 3 years ago

I use e-g in prose, but eg as a prefix here is fine I think, along with the 0., so the names will look like eg-0.6, eg-0.7, eg-master, etc.

I think the additional prefix keeps us flexible and doesn't make the name much longer.

Make sense!

IMO we should have a eg-master directory, that will always use a git dependency.

Makes sense too. Will this be pinned to a commit or just the latest commit on master?

rfuest commented 3 years ago

...so the names will look like eg-0.6, eg-0.7, eg-master, etc.

Looks good. Should we use something neutral instead of eg-master, like eg-next? This way we could keep the name if we decide to follow the trend of renaming master branches.

Makes sense too. Will this be pinned to a commit or just the latest commit on master?

IMO it should always use the latest commit. This way we could use a cron based CI job to check that our examples stay up to date.

jamwaffles commented 3 years ago

Ah good point, eg-next is a better name. I agree the latest commit is a good idea too. CircleCI can run builds on a schedule, but Github Actions could be used as well.