Add information about project name > directory name kebab-case conversion

[yshng]

Existing documentation directs users to name their project with underscores rather than hyphens or spaces.

Previously, when Arches created the project directory, it would use this project name as given, but now it converts it into kebab-case for the purposes of directory creation, and for writing to pyproject.toml . Presumably this is to conform with some external naming convention.

In practice, if you do input a project name with underscores, you get a directory structure such that the project directory has hyphens and the app directory uses underscores. This can sometimes cause hiccups with the automated creation of Arches instances if one is unaware that this is happening. (Of course, this is how we ended up discovering this to begin with)

As such, I would like to include information about the kebab-case project directory within the documentation, as well as mention the --directory option for choosing a custom name for the project directory. If this sounds good, I can write up the changes and submit a PR.

Thanks,
Lily

[tris-ots]

Thanks for writing this up, @yshng !
As an addendum, Lily pointed me to this section of the arches-admin code that should notify the user that their directory has been renamed, but it doesn't seem to do that for me on Arches 8.0.7:

(.venv) arches@amd64:~$ arches-admin startproject ar__ches
npm warn deprecated @types/minimatch@6.0.0: This is a stub types definition. minimatch provides its own type definitions, so you do not need this installed.
npm warn deprecated inflight@1.0.6: This module is not supported, and leaks memory. Do not use it. Check out lru-cache if you want a good and tested way to coalesce async requests by a key value, which is much more comprehensive and powerful.
npm warn deprecated whatwg-encoding@3.1.1: Use @exodus/bytes instead for a more spec-conformant and faster implementation
npm warn deprecated lodash.isequal@4.5.0: This package is deprecated. Use require('node:util').isDeepStrictEqual instead.
npm warn deprecated glob@7.2.3: Glob versions prior to v9 are no longer supported
npm warn deprecated glob@7.2.3: Glob versions prior to v9 are no longer supported
npm warn deprecated bootstrap-colorpicker@2.5.3: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.
npm warn deprecated bootstrap@3.4.1: This version of Bootstrap is no longer supported. Please upgrade to the latest version.

added 1451 packages, and audited 1452 packages in 4m

413 packages are looking for funding
  run `npm fund` for details

7 moderate severity vulnerabilities

To address issues that do not require attention, run:
  npm audit fix

Some issues need review, and may require choosing
a different dependency.

Run `npm audit` for details.
(.venv) arches@amd64:~$ ls -alh
total 60K
drwxr-xr-x 10 arches arches 4.0K Jan 25 00:20 .
drwxr-xr-x  4 root   root   4.0K Jan 23 14:56 ..
drwxr-xr-x  3 arches arches 4.0K Jan 22 00:37 .ansible
drwxr-xr-x  7 arches arches 4.0K Jan 25 00:24 ar--ches

[chiatt]

Thanks for writing this up, @yshng ! As an addendum, Lily pointed me to this section of the arches-admin code that should notify the user that their directory has been renamed, but it doesn't seem to do that for me on Arches 8.0.7:

Nice catch @yshng and @tris-ots. Could you submit an issue to core for this missing notification?

[ekansa]

@tris-ots @yshng Thanks for highlighting all of this! Is there something specific I should update in the documentation? @chiatt we may want to clearly specify Arches project naming conventions so they are in the docs and can be easily referenced.

[tris-ots]

Check me on this, @yshng - but my take would be that the docs should state the actual behavior, that underscores will be replaced with hyphens?

EDIT: I briefly confused myself and forgot that the documentation also tells you not to create a projectname containing a hyphen :)

[johnatawnclementawn]

Thanks for writing this up, @yshng ! As an addendum, Lily pointed me to this section of the arches-admin code that should notify the user that their directory has been renamed, but it doesn't seem to do that for me on Arches 8.0.7:

I'll just add that the reason why we're converting top-level directory names to kebab-case is to conform with Python package naming spec. With a lot more of Arches projects becoming Arches Applications that will be published to PyPI, we felt it necessary to nudge users starting a project to start with the right naming convention... sorry this hasn't made it's way to the docs, it looks I should have included it in this PR.

Here is a PR to fix the notice not being logged: archesproject/arches#12573

Edit: looking back at my docs PR #492, I remember the thinking was that we didn't want to clutter the front page with minutia of directory naming. The CLI reference page details the behavior, but do you all think that should be brought front and center in the Installation page?

[yshng]

Thanks @johnatawnclementawn and @chiatt for moving so quickly on the notice in core. I was out sick for a bit and am just now catching up here. I see now from @johnatawnclementawn's comment that this behavior is discussed in the CLI reference which is also linked from the Note underneath the installation instructions.

I think adding one sentence to the beginning of that note would suffice, e.g., "Running this command will install arches in the directory my-project where underscores in the project name are replaced with hyphens. [Note continues as written]" If that sounds okay, I can create a PR

[chiatt]

I think adding one sentence to the beginning of that note would suffice, e.g., "Running this command will install arches in the directory my-project where underscores in the project name are replaced with hyphens. [Note continues as written]" If that sounds okay, I can create a PR

Thanks @yshng - @johnatawnclementawn and I discussed this and we think we should simply prompt the user to decide if they want the folder name to be changed rather than making the change without their approval in advance.

[yshng]

Okay, sounds good @chiatt and @johnatawnclementawn! We can certainly work with that.