composer: `composer.json` does not allow comments

# file.json
{
  "key": "some comment here about key (this value gets overwritten)",
  "key": "some value"
}

$ php -r 'print_r(json_decode(file_get_contents("file.json"), true));'
Array
(
    [key] => some value
)

In any case, better to introduce YAML than to expand JSON.

Duplicate of #1988, #1778, #440, #159.

@cweagans I would not count on it. What you are proposing violates KISS principles.

We simply do not wish to end up having to support something like this:

Fixed the _comment validation in https://github.com/composer/composer/commit/98b0af1386f7ff730c3330e2525c1d66998c7f90 which makes official that “workaround”.

Another user added their name to the list of people wanting comments in composer.json by writing:

Please, provide some simple mechanism for comments. I just ran into a production issue that could’ve been avoided with proper comments.

I replied as above and he replied to me:

As the conversation(s) have shown, developers want a simple commenting mechanism, and the workarounds described here (what I can understand of them) aren’t encouraging. 😃 Try a quick Google search for “composer comments” or “comments in composer.json”-- you’ll find closed issues, feature requests, and questions, but nothing resembling a solid resolution or documented workaround. I don’t have a solution, but I’m adding my voice to the chorus of developers asking to make this a priority.

He’s since deleted his remarks for some reason. I didn’t mean to make him feel unwelcome, so I hope that’s not it. Anyway, he might not want to be part of the conversation any longer, so I won’t disturb him by @-mentioning his name again.

I don’t disagree with him and others’ remarks that we need comments in composer.json. However, I agree with @alcohol and @Seldaek that Composer shouldn’t add any features that would make it incompatible with standard JSON.

💡 Therefore, it seems that the correct long-term goal is to petition the keepers of the JSON standard to make allowances for comments.

In the meantime, we should use the workarounds mentioned in this issue to add comments. Personally, I like the strategy of using an attribute named “attribute_name-comment” to add a comment about an attribute named “attribute_name”.

The MakeUpYourMindException would break thousands of existing CI/CD systems out there not cleaning up their folders and suddenly seeing both files end up simultaneously.

What? That’s not true at all. If I have a project with composer.json in it and I upgrade to a version of Composer that has this new functionality, nothing changes. If I then add a composer.hjson (or whatever) without removing composer.json, then I get the exception. It takes two separate conscious actions to get to that point. It should not be a “suddenly everything is broken” kind of thing at all.

What is wrong with my solution? Or the one @Seldaek suggested (using _ as a key)? It’s backwards compatible, doesn’t require any changes, and makes all parties involved in this discussion happy.

I guess it works, but it’s very verbose and pretty suboptimal, but if that’s the only thing we’re going to be able to do, it’s better than nothing, I suppose.

But you want it to be the Composer team decision, seriously?

You know what I mean. It shouldn’t live outside of Composer.

But actual supported version by Composer is “php”: “^5.3.2 || ^7.0”. Why didn’t you check it out before offering?! […] Why composer.json does not support multiline? I want to write detailed description for my super-duper awesome package. Why composer.json does not support inheritance/reference? I want to reuse some code and adhere to DRY principle.

So? “You have to upgrade PHP to use the HJSON format in Composer.” Done. Or we could consider a different tool that’s arguably better for the job, but I’ve been purposely trying to not steer the discussion there (hint: it rhymes with BLAML).

In general, a lot of your arguments come down to “What if ____ happens or user wants _____?”. Taking a feature request to it’s most ridiculous extreme to disprove the need for the original feature request is kind of disingenuous, if you ask me. To the users that want imports or multiline or whatever, a “no, do it elsewhere” is acceptable. But the fact that there have been so many issues opened about wanting simple comments in a file that can get really damn complicated for large projects is telling. There is a need for this functionality.

Don’t do Package Management Driven Development! It is not important in most cases! If you really need it you get it by yourself (start using #5364 (comment)). I’m done and out from this discussion.

What? We’re not talking about an entire new development methodology here, man. We’re talking about adding comments. This should not be rocket surgery.

Fixed the _comment validation in 98b0af1 which makes official that “workaround”.

Thanks, @Seldaek. I appreciate that. Taking this a step further, If I were to implement something that satisfies the following criteria, would you be willing to consider it? And are there any criteria I’m missing?

• Adds support for a JSON superset or YAML
• 100% backward compatible and opt-in only
• Supported by Composer, Satis, and Packagist
• Doesn’t unacceptably bloat Composer
• Doesn’t change Composer’s version constraints to anything more restrictive

What is wrong with my solution? Or the one @Seldaek suggested (using _ as a key)? It’s backwards compatible, doesn’t require any changes, and makes all parties involved in this discussion happy.

Therefore, it seems that the correct long-term goal is to petition the keepers of the JSON standard to make allowances for comments.

They already have:

A JSON encoder MUST NOT output comments. A JSON decoder MAY accept and ignore comments.

• Douglas Crockford (creator of JSON)

Comments are not invalid in JSON per-se, they’re just supposed to be ignored. The JSON linters should support an option to do that.

and you don’t want the next developer to think

This is the point where you should stop thinking for other people, write important considerations about dependencies in your README or Wiki, and expect the next developer to read that before touching any of your code in highly invasive ways like the dependencies.

I also found that adding “packagist”: false to other repository structures, like the one in my example, it’s ignored.

You should open a new ticket regarding this with a minimalistic reproducible scenario. Cause that sounds like a bug to me if that is true 😃

Dependency related breakage can be subtle and difficult to track down. A comment is a low effort way to ensure that people don’t cause that kind of breakage (or perhaps even refer them to the relevant wiki page).

Leaving a comment is not thinking on somebody’s behalf. It’s a way of managing complexity and lowering cognitive load.

Hello, this is still an issue. Regression maybe???

Although this isn’t composer.json specifically this is just the requirements.txt file

I have an SO post as well: https://stackoverflow.com/questions/76860410/does-composer-not-support-comments-in-requriements-txt/76886280#76886280

This is my requirements.txt:

# This is a comment
python-json-logger==2.0.4
# Here's a private package
my_private_pypi_package==1.2.3

I get an error:

> gcloud composer environments update myenv  --format=json --project myproj --location=us-central1 --update-pypi-packages-from-file='requirements.txt'

ERROR: (gcloud.composer.environments.update) INVALID_ARGUMENT: Found 2 problems:

    1) Error validating key # Here's a private package. PyPI dependency name is not formatted properly. It must follow the format of 'identifier' specified in PEP-508.
    2) Error validating key # This is a comment. PyPI dependency name is not formatted properly. It must follow the format of 'identifier' specified in PEP-508.

@alcohol please refrain from using such imagery as it’s just not helpful and tends to devolve the discussion into a trollfest.

@cweagans no I’d still rather not have actual comments even if it’s BC because even if it’s opt in and everything it can still break third party tooling in potentially unpredictable ways, and the added value of comments isn’t worth it IMO vs the makeshift comments you can already use in the current state.

@stof The comment handling behavior for JSON is not strongly defined. Some parsers simply ignore them as they should.

What about simply adding support for JSON5 or HJSON with a different file extension? (i.e. composer.hjson or composer.json5 ?)

Proposed solutions and JSON spec aside, @Seldaek and @alcohol: Do you agree that comments in a composer.json would be helpful? If yes, what can I/we do to resolve this difficulty for Composer users? If no, why not?

@Seldaek:

1/2 have been suggested before, and they are not practical IMO because third party tooling needs to be updated and that kinda sucks.

“Third party tooling” meaning Packagist and Satis? I already volunteered to do the work for those projects. Also, note that both of the supersets of JSON suggested in option 2 are 100% backward compatible with regular JSON. That is, only people that opt-in to actually using comments in their root package’s composer.json will need to change their tooling to cope with comments in JSON. My guess is that most of the time, this functionality won’t be used in a package that actually gets pushed to Packagist anyway, though. It would be more useful for private, internal projects that are just pulling in dependencies from Packagist or whatever other repositories.

3 is feasible already, much like what @alcohol suggested. Validate will complain maybe but we could perhaps fix that. I use _ keys myself in some projects when I really need to explain why some dep is locked to some version. Sure composer validate sees it as invalid but it’s otherwise not an issue at all.

Well, composer validate actually runs as part of my build process. If composer validate says it’s bad, the build stops. That’s easily fixed, sure, but it’s also a pretty verbose way of writing comments.

4 is technically feasible, but tbh if it’s done as a third party tool that transparently does that + calls composer it has no overhead for users and it means it’s something we don’t need to maintain. I also don’t see the benefit of comments as justifying such a mess of having two files.

Yeah, this is definitely not an ideal solution. I only suggested it for the sake of completeness. Personally, I’d prefer to completely replace JSON with YAML, but since that hasn’t been received well for whatever reason, I’m trying to come up with other paths forward here.

@Seldaek As an aside, In response to https://twitter.com/seldaek/status/734778522087067648, I don’t mean to come across as overly combative here, but if people keep beating that horse, they must have a reason, no? We all acknowledge that comments are good, but every time something has been suggested that attempts to move Composer in that direction, the issue has been closed and conversation stops. That’s where my frustration is coming from, so apologies if that came across poorly.