search

JuliaLang / Compat.jl

Compatibility across Julia versions
Other
148 stars 117 forks source link

Reorder (and restructure) the sections in the README #678

Closed martinholters closed 4 years ago

martinholters commented 4 years ago

Previously, the sections were

This changes the order to

getting rid of the ambiguity where to put new macros and removing the "Module Aliases" section (if needed, these could probably go into "Renaming").

Also, the entry from #668 is moved from "Other changes" to "New functions and methods" as it is a new method.

Finally, presently empty sections get a "None." placeholder entry.

martinholters commented 4 years ago

As you also have some ideas for the README (#680), mind taking a look here and commenting, @oxinabox?

oxinabox commented 4 years ago

I suggest Supported syntax go at the bottom, as the @compat macro is rarely used, and having it at the top makes it look like all the other things require it

I'm not convinced that we need more than 2 sections listing features. one about @compat and one about everything else

martinholters commented 4 years ago

Yes, let's trim down the number of sections. I wasn't sure about keeping the empty ones anyway. If things start to become a mess, we can still re-introduce new sections as needed then.

Looking back at when we still had @compat entries in the README, they were always explicitly mentioning the macro, e.g. "@compat foo(; x, y) makes x and y required keyword arguments". So I'm not even convinced they need their own section. (Anyway, until development of Julia 2 starts, it seems unlikely that we will need to use @compat much.)

So maybe we can just collect all supported features in one section, tentatively title "Supported features"? That would leave

Nice and clean :smile: What do people think?

oxinabox commented 4 years ago

Sounds good to me

martinholters commented 4 years ago

Incorporated the sorting from #680 (newest on top) here and will merge soonish unless anyone objects.