Concerns About Repository Name about pml-changelog HOT 7 CLOSED

depending on whether you consider this Changelog as pertaining to the PML syntax in general, or to the PMLC tool specifically.

It concerns both. For example, changes to nodes and attributes are related to PML. Changes to the CLI (e.g. new commands) are related to PMLC.

users won't be able to fork more than one such repositories due to name-uniqueness restrictions. For this reason I'd argue that the current name violates good repository naming conventions.

That's a strong argument, indeed. All other arguments are correct too.

I believe it ought to be renamed to pml-changelog or pmlc-changelog

Yes. I suggest to rename it to pml-changelog.

from pml-changelog.

It concerns both. For example, changes to nodes and attributes are related to PML. Changes to the CLI (e.g. new commands) are related to PMLC.

In this case PML has the priority IMO, since PMLC is just a tool of the larger (and growing) PML ecosystem. This choice would also entail that any PML-relevant "news" of how PML syntax changes affect other tools should be mentioned in the Changelog — which is what has been happening so far, since new documents were also mentioned and linked here (e.g. the new PMLC CLI options documentation).

Yes. I suggest to rename it to pml-changelog.

Yes, Better now than later, so there are less cross-reference links to fix.

I'll rename my repository fork too, and then simply update all remotes URLs, GitHub will hand all the redirections so that the upstream vs fork connection is not lost (e.g. for proposing PRs when new branches are ahead of the upstream, etc.).

from pml-changelog.

If we change changelog to pml-changelog, then IMO we should also rename all other repositories, to be consistent.

A search for 'github repo naming convention' reveals that there are no official Github naming conventions, but the general recommendations are:

• Use only lower case alphanumeric characters
• Use '-' as word separator (no spaces, underscores, or CamelCase).
• Use semantic names, for example a name of the form [product/project name]-[purpose], which is what you suggested (see Try a Semantic Approach to Naming GitHub Repositories.

So, I suggest to to use the following repository names:

pml-companion-java
pml-changelog
pml-user-manual
pml-nodes-reference-manual
pml-commands-reference-manual
pml-advanced-features-manual

from pml-changelog.

If we change changelog to pml-changelog, then IMO we should also rename all other repositories, to be consistent.

That makes sense — even though the problem is strongly felt with the Changelog repository, adopting a consistent naming convention is good.

• Use only lower case alphanumeric characters.

The lowercase-only rule is not very strict, in fact many repositories do use capitalization in their names. I think that the "lowercase guideline" is part of the heritage of the Linux environment regarding files naming, and that the only reason it's still followed today it's because it simplifies typing file paths in case-sensitive environments like the Linux terminal.

But other than that, there's nothing wrong with using capitol letters in the repository names if it makes sense to do so. When it comes to practical things, on GitHub repository name operations (search, etc.) are case-insensitive since two repositories can't have names which are case-insensitively identical (i.e. myrepo = MyRepo = MYREPO).

But I think that lowercase names are just fine, especially since PML being an acronym would result in too many uppercase letters, which might look a bit loud.

So, I suggest to to use the following repository names:

Bear in mind that the repository name will also affect the GHPages website URL for those repositories that might end up using GHPages to provide documentation, etc.

For this reason, I wonder whether it's worth or not keeping the -java suffix in the proposed pml-companion-java repo name. It's true that in the future there might be new implementations of PMLC, but

1. Right now, the -java suffix could generate confusion rather then clarify, since there are no other PMLC incarnations (official or otherwise).
2. Even if/when there were other PMLC implementations, it would still make sense to have unified website, and the -java suffix doesn't help for this.
3. In the Asciidoctor project the asciidoctor repository is for the Ruby implementation (the first and original), while the repos of the JavaScript and Java implementations are named asciidoctor.js and asciidoctorj respectively. This has never been a source of confusion really, nor have I heard of the proposal to rename the Ruby implementation repository to asciidoctor.rb.

But then, of course, it largely depends on what you have in mind for the future, and the best decision here is what will ultimately prevent having to rename repositories once PML is widely adopted. So, if you're planning to have multiple PMLC implementations, and these are going to be all official and no one is going to be "more official" than the others, then it makes sense to preserve the -java suffix, and maybe reserve the pml-companion name for a common GHPages website introducing the tool and its various implementations.

Some of the proposed name are a bit long IMO (they eat up space in the terminal and are lengthy to type anywhere), and we could shorten them by adopting some well established shorthands:

They might not look as nice as the original, but they are much quicker to read and spot visually, and any computer user will know what "man" stand for. I think that userman/refman are better than user-man/ref-man since they are more readable, and the the added hyphen in feat-man is justified by the fact that "PML advanced features" and "Manual" are like separate components of the name, and because "User Manual" and "Reference Manual" are two types of manuals, but there's no such thing as a "Feature Manual".

In any case, you should be 100% convinced of each new name before renaming the repositories, since renaming is not an entirely painless operation — not only on the end users' side, who'll have to rename their forks, local clones and projects accordingly, but also for you since GH's redirection system will not allow you to re-use the old repository names in the future, since they'll always point to the new names.

from pml-changelog.

All documentation repositories have been renamed according to your suggestions:

pml-userman
pml-nodes-refman
pmlc-commands-refman (not pml-commands-refman)
pml-advanced-feat-man
pml-changelog

Repository converter will be renamed later.

from pml-changelog.

I've renamed my forks on GH accordingly, as well as my local clones and their remotes.

Let me know when you rename the PMLC repository too.

from pml-changelog.

Let me know when you rename the PMLC repository too.

It has been renamed to pml-companion.

from pml-changelog.