> It's also difficult to find documentation on what's in lib/
Can you give examples? If you give concrete examples we can try to improve matters.
Many libraries have a long header comment up top, like rocketnia's ns.arc.
Anarki comes with online help. Try saying `(help deftem)` at the commandline. Admittedly online help is patchy inside lib/ but make it a habit to check it if you aren't already.
Lastly, it's worth looking inside the CHANGES/ directory for major features.
> ..or to know how stable the code is, because no one seems to use most of it.
If by 'stable' you mean "we shouldn't change it", then nothing is stable, inside or out of the lib/ directory.
If by 'stable' you mean "working as intended", then tests are our proxy for intent. There's tons of tests under lib/ and I run the tests fairly often. If a library doesn't have tests then I have a lot less to say about it.
So "no one seems to use most of it" feels like an exaggeration. Most code under lib/ is constantly being monitored for bitrot.
> The dependencies for news should be libraries, but they still seem to bake in too many assumptions and interdependencies to be useful as standalone libraries.
I think here you're cargo-culting[1] notions of "good practice" without considering their costs. Not everything that other people use is a good idea for Arc. We have a tiny number of users, which makes it better to keep the community in a well-integrated codebase rather than fragment it across several "lines". Interfaces have a tendency to balkanize users on one side or other of them. We don't want that; our tiny community doesn't really benefit from the scaling benefits that interfaces provide.
If and when Arc grows 10x or something, and we have three different sets of html generation libraries, we can think about drawing better lines. Until then I suggest a different "best practice": YAGNI[2]
But those are comments from the same person I'm responding to?
Did you perhaps have a similar opinion as well? I certainly recall other people asking for a package manager.
To be clear, what I said is just my opinion, and I should have said "we don't need that" or "it's a bad idea" rather than "we don't want that", which sounds like I'm speaking for others. If a couple of us feel strongly about adding interfaces, you should feel free to do it and see how it goes. If I'm right then you'll eventually realize that it's only serving as bureaucracy. If you do enjoy it then I'll eventually realize that I'm wrong ^_^
I think API boundaries arise naturally from syntax that doesn't fit on one screen. Edits to one piece of code can only be quick and easy if they manage to preserve the assumptions that make the rest of the code work. These assumptions form an API boundary, and at some point it becomes easier not to break the code if that boundary is documented and verified.
Currently, we break up the API boundaries in Anarki by function and by file. We document the function APIs with docstrings, and we write verified documentation for them with (examples ...). We verify the file APIs with "foo.arc.t" unit test files.
If we put more effort into documenting or verifying those boundaries, it would hardly be a big change in how we use the language. We could perhaps add a bunch of "foo.arc.doc" files or something which could compile into introductory guides to what foo.arc has to offer (whereas the docstrings still act as API documentation). And we could perhaps add an alternative to Anarki's (require ...) that would load a library in a mode that faster faster, abiding by an interface declared in a "foo.arc.i" file.
It seems like the most drastic change in philosophy would happen if we broke Anarki apart into sections where if someone's working on one section and discovers they're breaking something in another section, they don't feel like they can fix it themselves.
I suppose that happens whenever people put Arc libraries in their own separate GitHub repos. There are actually a number of those repos out there, including my own (Lathe). Even aw, who was a strong believer in avoiding unnecessary black-box interface boundaries, would still put things in various repositories, and the hackinator tool would collect them into one file tree.
It also happens naturally with poor knowledge sharing. Seems like despite my attempts at explaining ns.arc, I'm still the only one with a very clear idea of how it works and what it's good for, so other people can't necessarily fix it when it breaks.
(Come to think of it, that makes ns.arc a great test case for pulling out an Anarki library into its own repo. That'd save other Anarki maintainers the trouble of having to fix it to keep Anarki's tests running.)
Hmm, even if some libraries are maintained separately from the Anarki repo, Anarki's unit tests can still involve cloning some of those repos and running their tests. If Anarki maintainers frequently break a certain library and want to help maintain it, they can invite its developer to fold it into the Anarki repo. And if the developer wants to keep maintaining it in their own repo, the Anarki project can potentially use a hackinator-style approach to maintain patches that it applies to those libraries' code. We have a lot of options. :)
"Hmm, even if some libraries are maintained separately from the Anarki repo, Anarki's unit tests can still involve cloning some of those repos and running their tests. If Anarki maintainers frequently break a certain library and want to help maintain it, they can invite its developer to fold it into the Anarki repo. And if the developer wants to keep maintaining it in their own repo, the Anarki project can potentially use a hackinator-style approach to maintain patches that it applies to those libraries' code. We have a lot of options. :)"
This would be fine. Whether we consider something an API has nothing to do with how we divide code into repositories or sections. Perhaps the key is to know who is calling us. I'd be happy to provide a guarantee to anyone who "registers" their repository with Anarki: if it's easy for me to run your codebase, I'll check it everytime I make a change to Anarki, and ensure that it continues to pass all its tests. If I break an interface, I'll fix all its callers and either push my changes or send the author a PR.
I don't know yet how "registering" would work. But we can start with something informal.
>I don't know yet how "registering" would work. But we can start with something informal.
Perhaps just the functionality to clone a repo into /lib under the requisite namespaces as a way to include remote dependencies, including pinning to branch and version? No need to "register" anything at first.
"It seems like the most drastic change in philosophy would happen if we broke Anarki apart into sections where if someone's working on one section and discovers they're breaking something in another section, they don't feel like they can fix it themselves."
Exactly! It's a huge problem in the programmer world today that we are indisciplined about this distinction. There's a major difference between making a boundary just to make edits easy and "APIs". APIs are basically signalling to most people that they shouldn't be crossing them, and guaranteeing that anybody calling them will be able to upgrade without modifying their code. That is worlds away from just not being able to see everything on a single screen.
Since we use words like "abstraction" and "interface" for both situations, it is easy to cross this line without any awareness that something big and irreversible has changed.
Currently nothing in Anarki is an API. I recommend we be restrained in using that term, and in introducing any APIs.
"There's a major difference between making a boundary just to make edits easy and "APIs"."
Maybe there's a difference somewhere in what we mean by "API." There's a distinction to make, but I wouldn't make that one.
I'm saying APIs arise naturally at boundaries people already feel aren't worth the effort to cross for various plausible reasons. Recognizing an API boundary is a positive thing: Then we can talk about it and help people understand the ways in which it's worth it for them to cross the boundary. But talking about it also makes it something people form as a concept in their mind and form expectations around, so it can become a more imposing boundary that way if we're not careful. We should seek a sweet spot.
The important distinction is that sometimes the reasons people don't cross boundaries are good ones, and sometimes they're baloney.
I think what you and I want to avoid for Anarki is documentation that gives people baloney reasons to think it's not worth it for them to edit the Anarki code.
While we can try to minimize the good reasons that exist, and we can encourage people to try it before they knock it, there's no point in denying that the good reasons sometimes exist.
If you ask me, the reason we have to settle for a "sweet spot" is totally a consequence of the fact that Anarki is made of text. Text loves bureaucracies. Someone sees text, they ask for the Cliff's Notes, and then someone has to maintain the Cliff's Notes.... So you've gotta get rid of the text, or you'll have an API boundary.
Programming without bureaucracy would be like having a conversation without writing it down. I believe in this. I think conversational programming is exactly what we can do to simplify the situation of programming in the world, and Era's my name for that project, but Anarki is a more traditional language, and it takes a more traditional trajectory into APIs.
Our documentation can try to convey "This is all subject to change! Edit it yourself, open an issue, or drop by on Arc Forum for some help! We count on contributions like yours to make Anarki a good language. Since others are welcome to do the same thing, watch out for changes in this space." We could put an "unstable, just like everything else here" tag on the corner of every single documentation entry.
Anarki is far from the only unstable codebase people have ever seen. Being a Node.js user, my code has regularly been broken by upgrades, and Node.js isn't even a version 0.0.x project. I think only a certain number of people would mind if Anarki promised stability and then couldn't deliver on it, let alone mind if Anarki made it clear in the API documentation that there was nothing stable to find there in the first place.
---
"guaranteeing that anybody calling them will be able to upgrade without modifying their code"
You know me well. I probably said that pretty insistently in the past. It's something obsess over and a major requirement I have for code I write (and hence all its dependencies), even though things like Node.js show me it's not a current norm in software.
It's the 100-year language ideal. Spend a lot of time to get the axioms just right, and then the language is stable and nobody ever feels the need to change it since there's nothing to improve on! In 100 years, Arc is supposed to be the language that's too perfect to be anything but the stablest language around.
I still believe in that ideal, but not in quite the same way. People will come up with a reason to promote their alternative language, even if it's just to say they're different than their parents. But I do believe languages can be designed to be more compatible with their forks, even to the point where it's difficult to say where one language ends and another begins. The resulting unified "ecosystem of all languages" could have a much simpler design than the "ecosystem of all languages" we currently have.
That's also part of my approach in Era. I make decisions in those codebases with the goal of simplifying the ecosystem of all languages.
I don't think this is something I would pursue in Anarki. Arc was very far from the the 100-year language upon release, it was unstable, and it seems like Anarki has pretty much been maintained by and for people who could embrace that part of Arc's journey.
