Opened 3 weeks ago

Last modified 2 weeks ago

#34526 needs_work enhancement

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

Reported by: Matthias Köppe Owned by:
Priority: major Milestone: sage-9.8
Component: documentation Keywords:
Cc: Dima Pasechnik, Kwankyu Lee Merged in:
Authors: Matthias Koeppe Reviewers:
Report Upstream: N/A Work issues:
Branch: u/mkoeppe/move__mathematical_software_landscape__from_trac_wiki_to_manual (Commits, GitHub, GitLab) Commit: cfce091fecee537040d612098a22852d9f083c36
Dependencies: Stopgaps:

Status badges

Description (last modified by Matthias Köppe)

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.

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

Change History (22)

comment:1 Changed 2 weeks ago by Matthias Köppe

Cc: Dima Pasechnik added

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

comment:2 Changed 2 weeks ago by Matthias Köppe

Branch: u/mkoeppe/move__mathematical_software_landscape__from_trac_wiki_to_manual

comment:3 Changed 2 weeks ago by Matthias Köppe

Commit: 972afeb1e9ef210ed5d6bc4a828402149910eebe

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:

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

comment:4 Changed 2 weeks ago by git

Commit: 972afeb1e9ef210ed5d6bc4a828402149910eebecfce091fecee537040d612098a22852d9f083c36

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

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

comment:5 Changed 2 weeks ago by Matthias Köppe

Authors: Matthias Koeppe
Cc: Kwankyu Lee added
Status: newneeds_review

comment:6 Changed 2 weeks ago by Kwankyu Lee

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

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

comment:7 Changed 2 weeks ago by Matthias Köppe

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.

comment:8 in reply to:  6 ; Changed 2 weeks ago by Matthias Köppe

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.

comment:9 Changed 2 weeks ago by Matthias Köppe

Description: modified (diff)

comment:10 in reply to:  7 Changed 2 weeks ago by Kwankyu Lee

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?

Last edited 2 weeks ago by Kwankyu Lee (previous) (diff)

comment:11 Changed 2 weeks ago by Matthias Köppe

Status: needs_reviewneeds_work

Yes, this makes sense.

comment:12 in reply to:  8 ; Changed 2 weeks ago by 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 :)

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

Or we go back to sagemath wiki?

comment:13 Changed 2 weeks ago by Matthias Köppe

Description: modified (diff)

comment:14 in reply to:  12 Changed 2 weeks ago by Matthias Köppe

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

comment:15 in reply to:  12 Changed 2 weeks ago by Matthias Köppe

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 https://github.com/sagemath/trac-to-github/pull/4 that makes it easier

comment:16 Changed 2 weeks ago by 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.)

comment:17 Changed 2 weeks ago by Matthias Köppe

Summary: Move "mathematical software landscape" from Trac wiki to manualBroaden the developer's guide to more than just sagelib development

comment:18 in reply to:  8 ; Changed 2 weeks ago by 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.

comment:19 in reply to:  16 ; Changed 2 weeks ago by 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?

comment:20 in reply to:  18 ; Changed 2 weeks ago by 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 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

Last edited 2 weeks ago by Dima Pasechnik (previous) (diff)

comment:21 in reply to:  19 Changed 2 weeks ago by Matthias Köppe

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?

comment:22 in reply to:  20 Changed 2 weeks ago by Matthias Köppe

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.

Note: See TracTickets for help on using tickets.