Issues to solve before the release of this package

[mmatera]

Before the release, I hope to fix the following things, and I plan to do in the following order:

• 1. Implement fixes to pass all the existing tests.
• 2. Add github actions to reinforce that behaviour.
• 3. Fix the documentation for all the symbols. Add summary_text, and URL references.
• 4. try to improve a little bit the implementation of _create_graph.
• 5. See if it is possible to improve the context name to use Pymathics`graph`.
• 6. Move doctests to pytests.

Of course, if someone else wants to tackle any of these issues in another order, please go ahead, but I guess it is easier to make small fixes according to what is was expected to get when the module was written, and then improve over it.

[rocky]

Thanks for opening this and working on it.

4: is vague - it is not a measurable goal.
5: This is most-likely going to require a change in mathics-core.

Overall I think what we need to do is plan this as two release a 6.0.0 release to match the 6.0.0 release of mathics-core.

x.0.0 releases are notoriously flaky, so it is okay if there are things that are still to be done.

So what is needed is a list if minimum things that must be done before release. And here, correcting the documentation and commenting our skipping failing tests is about it.

Actually, there was something else that I had started to do last weekend but didn't finish - put the builtins into sections that more closely correspond to some WMA section.

[rocky]

Over the weekend I may arrange the sections to align more closely. But that is a lower priority thing. The higher priority thing is to see if we can get the documentation into the LaTeX PDF.

[mmatera]

Regarding 4., If you look at the code of that function, I guess you are going to agree that is not a vague goal. In the process, I guess that we are going to find a couple of other functions like that.

[mmatera]

Regarding 5. I just hit the need to make a fix in mathics-core.

[rocky]

Regarding 5. I just hit the need to make a fix in mathics-core.

(I had mentioned it in passing a while ago when I first realized this.)

[rocky]

Regarding 4., If you look at the code of that function, I guess you are going to agree that is not a vague goal. In the process, I guess that we are going to find a couple of other functions like that.

There is no question that the code needs improving. Please do that and put in PRs for the improvements so we can discuss. However please do that after the mathics-core 6.0.0 release and the pymathics-graph 6.0.0 release.

When a statement like "we should not release until X is done" is made, the X should be something concretely measurable.

"Improve code" is not in that category.

Let me backup a little bit to review how we got here....

We would like to get a Mathics3 core 6.0.0 release out. Before releases it seems like this is the time to go over documentation, because the releases have documentation that is more visible than documentation other times. Also, documentation is one of those things that tends to get put off in favor of other things.

Similarly, before a release I like to review some of the technical-debt items or carry-over items from the last release that have also been largely ignored because we are constantly doing new shiny things rather than working on the more boring and mundane but foundation-building things,like turning "sandbox" tests into pytests, (as a concrete example), or organizing the module structure for builtins to be more logical - think the "miscellaneous" mathics.core.lists module.

One of the carry over items from the last Mathics3 release was going over the Mathics3 Modules such as pymathics graph and pymathics natlang.

Previously, I had done basically the minimum needed back then to get these to work with the 5.0 API. With respect to pymathics.graph there was a major NetworkX upgrade that went on from NetworkX 1.x to NetworkX 2.x and so it was a lot of work just to deal with that. (BTW there is the same that could be done to support NetworkX 3.x now. But again, that can be deferred.)

Ok. So now we find ourselves close to the next release and there is some unfinished business from last release. And there is also the issue of going over documentation.

This is where I am coming from when I picked this up again.

Although there is much work that could be done on pymathics.graph, right now we would like the minimum to get this working in a way that is not obviously shoddy.

I thought we had discussed this before. After release we can make another, better mathics graph release.

The minimum would be:

• Get tests not to error either by fixing them or by skipped or expected failure
• Get the docs and test incorporated into the LaTeX PDF. (I will do this)
• Get the organization roughly right. (This is easy and I will do this after the above).

The mathics-core 6.0.0 has breaking API changes. Therefore we have to have some sort of pymathics-graph release at about the same time as the mathics-core 6.0.0 release.

The ugly code here works or sort of works. It is basically the code that was there from whoever added this originally.

After the mathics-core 6.0.0 release and the pymathics-graph release, personally I think it an excellent time to clean up code and come out with a 6.0.1 release. The reason I think it excellent after is also because we really need to give some grace period after the 6.0.0 before doing major refactoring in case there are problems with the release.

And also keep in mind that before the mathics-core release we need to do the same sorts of things we are doing here to in the pymathics-natlang repository.

This is another reason why we need to do the minimum here. And come back to it.

[mmatera]

OK, regarding 4, the idea would be to at least make the _create_graph routine a little bit more readable, and try to ensure that the basic cases we have in the documentation are produced correctly. Just with this, I guess half of the persistent errors would be solved. Then, we can move the remaining to pytests and mark them as xfail / skip.

Regarding 5., I would like to try implement small fixes in mathics.core.parser to bugs that emerge working out the previous items (if they are not too complicate). For example, I found that mathics.core.parser assigns by default the System context to every symbol that does not have an explicit context. Something similar happens with the symbol names in rules.
If it does not takes too much, I would like to try fixing these issues before the release of mathics-core.