proposal that repositories be per topic rather than per class

Each repository should represent a topic instead of a class, such as git, python, pkgbuild, goat sacrificing, etc. The repositories are to be maintained by the community rather than by the instructors alone and will contain materials which can be used by a class on that topic. Annotated tags point to commits used in a class. The table of past classes on the ArchWiki page will have an extra column linking to a tarball of the contents of the commit of the materials used in a class. (The ability to link to a tarball is a GitHub specific feature.)

We need to make decisions first.

• What is the naming scheme for a repository? class- or something else?
• What is the naming scheme for annotated tags? The only information needed to be conveyed is the date and time of the class and that it represents the materials used in a class.
• Do we need to name the commits in the announcement files in the past-classes repository or are annotated tags sufficient?
• Anything else I didn't think of?

We will need to implement the following.

• Decide and agree upon the questions in the previous list.
• Rename the repositories according to the new naming scheme.
• Create annotated tags for each past class. Add the commit hashes to the announcement files if we've decided to do that.
• In the past classes table on the ArchWiki, add column with links to tarballs for each class.
• Update guides/tutorials as necessary.

Currently the repositories represent classes, such as git-for-gits, python-beginners, and intro-to-appeasing-the-pacman-god. For a new class one would make a new repository. Users who want to access materials will have to clone the git repository. This scheme has several obvious flaws. Users who do not know how to use git are greatly inconvenienced, especially if their goal is to get the materials to learn git. Users have to do a lot of work to get the version of the materials which correspond to the class logs they are reading. First they need to compare the date of the log with the commit history to identify the specific commit. Then they need to checkout that commit. There is greater burden on teachers to create and maintain materials. The community cannot contribute without the teacher reviewing and accepting the pull requests. Most teachers in the past weren't interested in this much of work and I doubt many teachers of the future will be either. This proposed change is needed for all of these reasons, and may be a few more I've forgotten.

[eli-schwartz]

I'm not positive what the naming scheme should be (in fact, we'd probably have a wiki table and something in this repo, linking to classes on a conceptual level, which are more descriptive than a repo name, so I consider this of lesser importance).

Pointing to specific media is definitely something I can talk about though. 😄 We do not want people to hunt down specific commits, annotated tags are superior specifically because they are meant to be human-readable pointers to unique commit hashes.
I'd suggest using for example 2018.01.11-name-of-class, alternatively we could tag the same commit twice as 2018.01.11 and name-of-class but that would probably lead to confusion if someone wanted two editions of the same class...

We could also make the Github Releases page show something slightly nice looking for each classroom release, in case users start looking there instead of the wiki table.

[polyzen]

I still prefer just one classes repo, with topics as subdirectories. The starter repo also falls under this issue, and would also become a subdirectory. past-classes and the rest will remain as they are. <3 Having seperate topic repos/admins doesn't seem to simplify anything, causes fragmentation, and, with that, some of the repos could likely fade away. A singular repo increases exposure, making it easier for users and teachers to get support or their PRs reviewed.

• naming scheme for a repository: classes
• naming scheme for annotated tags: Eli's suggestion seems fine. Not sure where to find a standard/precedent on that. Maybe name-of-class/2018.01.11. /shrug
• Do we need to name the commits in the announcement files in the past-classes repository or are annotated tags sufficient? tags++
• Anything else I didn't think of? The only problem I can think of is perhaps confusion if a class is rerun without any changes to its materials. :p

[eli-schwartz]

Anything else I didn't think of? The only problem I can think of is perhaps confusion if a class is rerun without any changes to its materials. :p

Easy, we can just re-tag the same commit. :p

I guess we agree on the following.

• Keep materials by topic rather than by class.
• Annotated tags are sufficient and no need to save commits in announcement files.

I like the idea with the Github Releases page. I have never made a GitHub Releases page and defer to you folks.

For the names of annotated tags, we've had a class which ran twice in the same day (CalimeroTeknik's PKGBUILD class). I can imagine it happening again with a future class. How about this scheme, class-yyyy.mm.dd-hh:mm. In here "class" is just a literal string and not standing for anything. That would distinguish it from other kinds of annotated tags, should people decide to tag for other purposes.

The idea of putting all the class materials in a single repository with separate directories for each topic sounds simpler. I have two issues with it.

1. Downloading a tarball for a commit would download all materials. This would be annoying for users who only want the materials for a single class. May be if GitHub can generate a tarball for a single directory in a specific commit?
2. It muddles the history. Separate histories for separate concerns. In git there are only two ways to do this, separate repositories or separate branches. A separate branch for each topic would be a pain to work with.

A single repository would not prevent topics from being ignored. It would make it harder to see which topics are being ignored,

[eli-schwartz]

Github cannot generate a tarball for a single directory in a specific commit. In theory the git-archive(1) backend supports this, but Github does not implement it, nor I think does any other web interface for git repositories.

The git protocol does not support cloning a single directory. The subversion protocol does, and Github even supports checking out a git repository over subversion, using svn checkout https://github.com/lodash/lodash/trunk/ for the root repository, and https://github.com/lodash/lodash/trunk/path/to/subdir via subversion's native subdirectory handling.
That being said, "subversion" == "ewwwwwwwww". Need I say more? 😛

...

Separating history is quite trivial, assuming by trivial you mean "people who understand git can do it".
git log subdir/ can be used to hack apart the histories of different subdirectories and ignore the commits you think are uninteresting.

Github also offers an interface for opening a subdirectory in the browser viewer, and clicking on the "History" button from there to show a directory history like this: https://github.com/archclassroom/archclassroom.github.io/commits/master/guides

You can then look at the full commit across all directories, since unlike cgit, Github does not offer the ability to restrict the commit diff. See for example a recent commit to the Arch Linux history for our linux kernel package and how it says "Diffstat (limited to 'trunk')"

I guess this is probably not a problem if people aren't committing changes to multiple directories at a time.

[polyzen]

How about this scheme, class-yyyy.mm.dd-hh:mm

Sounds good to me, or class/yyyy.mm.dd-hh:mm. Perhaps we specify the time only when such cases are planned.

Downloading a tarball for a commit would download all materials.

They could perform a sparse checkout. I imagine most would just read the materials on GitHub.

It muddles the history.

It's also a good practice to add "types" and "scopes" (as I've seen them called) to commits when handy, eg. Bash: Intermediate: Simplify examples.

A single repository would not prevent topics from being ignored. It would make it harder to see which topics are being ignored,

Possibly, but it would easier to apply policies to all topics at once with a single repo.

[eli-schwartz]

They could perform a sparse checkout. I imagine most would just read the materials on GitHub.

Sparse checkouts download all history to the git objects directory, then, during the "extract files from the object store onto disk" stage, they avoid cluttering up the directory tree layout with the files you asked to ignore.

It also requires using (and installing) git, even if someone didn't want the history.

[meskarune]

I like the simplicity of having a single classes repo with topics as directories, and it would make irc integration a lot easier: github.com/archclassroom//settings/hooks/new?service=irc Its also the way we have done things for a while and hasn't caused much issues.

With topic repos however we can give teachers access to only the specific classes they teach. Students would also be able to download things via topic rather than pull down every class ever. If we end up with more videos, presentations, etc it could cause a single class repo to grow rather large, but that could be putting the cart in front of the horse.

A current topic list might look like this:

• Version Control
  • git
• Programming
  • python
  • bash
• SysAdmin
  • kernel compilation
  • PKGBUILDs
  • How to debug in Linux (future class maybe?)

We could maybe keep the topics somewhat broad though so we don't have a million different repos to keep track of. It's totally possible that Programming could grow rather large and might need to be split into functional programming and object-oriented programming, or even per language, though that could end up unwieldy.

[polyzen]

I feel we should keep topic scopes narrow (eg. Git/Git for gits) until there are topics to group against (eg. version control/Mercury/Mercury for gits). PKGBUILDs may fit better under Bash.