Broaden the developer's guide to more than just sagelib development

[mkoeppe]

We broaden the Sage developer's guide, so that it gives guidance to users/developers how they can contribute, not limited to just the Sage library.

• Move https://trac.sagemath.org/wiki/WikiStart#Surveyingthemathematicalsoftwarelandscape to front page of developer's guide
• Merge https://wiki.sagemath.org/CodeSharingWorkflow into developer manual #34554 Merge https://wiki.sagemath.org/CodeSharingWorkflow into developer manual
• Add short chapter on distribution packaging

Preview of the new material: https://cfce091fecee537040d612098a22852d9f083c36--sagemath-tobias.netlify.app/developer/index.html

CC: @dimpase @kwankyu

Component: documentation

Author: Matthias Koeppe

Branch/Commit: u/mkoeppe/move__mathematical_software_landscape__from_trac_wiki_to_manual @ cfce091

Issue created by migration from https://trac.sagemath.org/ticket/34526

[mkoeppe]

comment:1

https://github.com/sagemath/trac-to-github does not seem to do a good conversion of this complex table.

Instead I saved the page as HTML and used pandoc -f html -t rst --wrap=none on the result

[mkoeppe]

Branch: u/mkoeppe/move__mathematical_software_landscape__from_trac_wiki_to_manual

[mkoeppe]

Commit: 972afeb

[mkoeppe]

comment:3

I've now manually converted it to a list-table. https://sublime-and-sphinx-guide.readthedocs.io/en/latest/tables.html#list-table-directive

---

New commits:

972afeb

src/doc/en/developer/index.rst: Add software landscape table from https://trac.sagemath.org/wiki/WikiStart#Surveyingthemathematicalsoftwarelandscape

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

cfce091

src/doc/en/developer/index.rst: Fix transition

[sagetrac-git]

Changed commit from 972afeb to cfce091

[mkoeppe]

Author: Matthias Koeppe

[kwankyu]

comment:6

I don't think this content has a place in the developer manual.

Why don't you move it to github sage wiki?

[mkoeppe]

comment:7

I think it very much belongs in the developer manual. It makes an important point: Contributing to Sage does not necessarily mean to contribute to the Sage library. I want to broaden the developer's guide so that it captures a broader profile of developers and contributions.

[mkoeppe]

comment:8

Replying to Kwankyu Lee:

Why don't you move it to github sage wiki?

We haven't made a decision yet to use the GitHub wiki.

Moreover, I think it is not a good replacement for material that we now have on our wikis: GitHub wikis are not indexed by search engines.

[kwankyu]

comment:10

Replying to Matthias Köppe:

I want to broaden the developer's guide so that it captures a broader profile of developers and contributions.

Then change the title of ticket and do more work. Only adding "mathematical software landscape" at the introduction of the developer manual seems unbalanced to me.

Perhaps you don't really want to do the work as we did not move to github yet. Then set it "needs work" now?

[mkoeppe]

comment:11

Yes, this makes sense.

[kwankyu]

comment:12

Replying to Matthias Köppe:

Moreover, I think it is not a good replacement for material that we now have on our wikis: GitHub wikis are not indexed by search engines.

Then this is an argument to keep using trac at least for wikis :)

Perhaps we will be forced to use github wiki after the migration...

Or we go back to sagemath wiki?

[mkoeppe]

comment:14

Replying to Kwankyu Lee:

Or we go back to sagemath wiki?

No, that's not suitable. Nobody can edit it - except for people with legacy Trac accounts

[mkoeppe]

comment:15

Replying to Kwankyu Lee:

Replying to Matthias Köppe:

Moreover, I think it is not a good replacement for material that we now have on our wikis: GitHub wikis are not indexed by search engines.

Then this is an argument to keep using trac at least for wikis :)

I think it is a possibility that we keep using the Trac wiki for a while, yes. The conversion script does tickets and wiki separately. In fact, I just sent a PR sagemath/trac-to-github#4 that makes it easier

[mkoeppe]

comment:16

(What I don't know is whether Trac can be configured to be read-only for tickets, but read-write for wiki.)

[kwankyu]

comment:18

Replying to Matthias Köppe:

Moreover, I think it is not a good replacement for material that we now have on our wikis: GitHub wikis are not indexed by search engines.

The final comment here

https://github.com/orgs/community/discussions/4992#discussioncomment-1448177

seems to say this is not true for some popular wikis.

[dimpase]

comment:19

Replying to Matthias Köppe:

(What I don't know is whether Trac can be configured to be read-only for tickets, but read-write for wiki.)

why don't we migrate wiki to GH, too?

[dimpase]

comment:20

Replying to Kwankyu Lee:

Replying to Matthias Köppe:

Moreover, I think it is not a good replacement for material that we now have on our wikis: GitHub wikis are not indexed by search engines.

The final comment here

https://github.com/orgs/community/discussions/4992#discussioncomment-1448177

seems to say this is not true for some popular wikis.

This appears to be about questionable Google's practice. Somebody there comments
about being unable to find anything on GitHub using https://www.google.com/search?q=%22lunar+lander+game%22
Indeed, it doesn't show anything on GitHub on the 1st page.
However, https://www.google.com/search?q=%22lunar+lander+game%22+%22github%22
does show GitHub stuff!

That is, Google does index GitHub, it just doesn't want to show it, unless asked pointedly.

And https://www.google.com/search?q=%22lunar+lander+game%22+%22github%22+%22wiki%22 does show some wikis there, too

[mkoeppe]

comment:21

Replying to Dima Pasechnik:

Replying to Matthias Köppe:

(What I don't know is whether Trac can be configured to be read-only for tickets, but read-write for wiki.)

why don't we migrate wiki to GH, too?

I'm saying it does not necessarily have to be done at the same time. Easier, no?

[mkoeppe]

comment:22

Replying to Dima Pasechnik:

Replying to Kwankyu Lee:

Replying to Matthias Köppe:

Moreover, I think it is not a good replacement for material that we now have on our wikis: GitHub wikis are not indexed by search engines.

The final comment here

https://github.com/orgs/community/discussions/4992#discussioncomment-1448177

seems to say this is not true for some popular wikis.

This appears to be about questionable Google's practice. Somebody there comments
about being unable to find anything on GitHub

Specifically, GitHub wikis, not GitHub as a whole obviously!

And it seems that it's just that GitHub is just using robots.txt on the wikis. I haven't checked.