From 3f51b7c68f36bf7405490aba26edbee1d5b70233 Mon Sep 17 00:00:00 2001 From: Fabrizio Balliano Date: Wed, 4 Jan 2023 11:08:39 +0000 Subject: [PATCH 1/4] Create 0000-migrate-readthedocs-to-awesome-format.md --- ...0-migrate-readthedocs-to-awesome-format.md | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 draft/0000-migrate-readthedocs-to-awesome-format.md diff --git a/draft/0000-migrate-readthedocs-to-awesome-format.md b/draft/0000-migrate-readthedocs-to-awesome-format.md new file mode 100644 index 0000000..7daabe5 --- /dev/null +++ b/draft/0000-migrate-readthedocs-to-awesome-format.md @@ -0,0 +1,35 @@ +# {{TITLE: a human-readable title for this RFC!}} + +## Summary + +{{A concise, one-paragraph description of the change.}} + +## Motivation + +{{Why are we doing this? What pain points does this resolve? What use cases does it support? What is the expected outcome? Use real, concrete examples to make your case!}} + +## Detailed Explanation + +{{Describe the expected changes in detail, }} + +## Rationale and Alternatives + +{{Discuss 2-3 different alternative solutions that were considered. This is required, even if it seems like a stretch. Then explain why this is the best choice out of available ones.}} + +## Implementation + +{{Give a high-level overview of implementation requirements and concerns. Be specific about areas of code that need to change, and what their potential effects are. Discuss which repositories and sub-components will be affected, and what its overall code effect might be.}} + +{{THIS SECTION IS REQUIRED FOR RATIFICATION -- you can skip it if you don't know the technical details when first submitting the proposal, but it must be there before it's accepted}} + +## Prior Art + +{{This section is optional if there are no actual prior examples in other tools}} + +{{Discuss existing examples of this change in other tools, and how they've addressed various concerns discussed above, and what the effect of those decisions has been}} + +## Unresolved Questions and Bikeshedding + +{{Write about any arbitrary decisions that need to be made (syntax, colors, formatting, minor UX decisions), and any questions for the proposal that have not been answered.}} + +{{THIS SECTION SHOULD BE REMOVED BEFORE RATIFICATION}} From 0596d5da867bd15de9c0d4c08f9bb4f29d0311cf Mon Sep 17 00:00:00 2001 From: Fabrizio Balliano Date: Wed, 4 Jan 2023 13:24:50 +0000 Subject: [PATCH 2/4] Initial commit --- ...0-migrate-readthedocs-to-awesome-format.md | 37 +++++++++---------- 1 file changed, 18 insertions(+), 19 deletions(-) diff --git a/draft/0000-migrate-readthedocs-to-awesome-format.md b/draft/0000-migrate-readthedocs-to-awesome-format.md index 7daabe5..9212427 100644 --- a/draft/0000-migrate-readthedocs-to-awesome-format.md +++ b/draft/0000-migrate-readthedocs-to-awesome-format.md @@ -1,35 +1,34 @@ -# {{TITLE: a human-readable title for this RFC!}} +# Migrate openmage.readthedocs.io to Awesome OpenMage ## Summary -{{A concise, one-paragraph description of the change.}} +This RFC proposes to remove https://openmage.readthedocs.io and migrate its contents to the ["awesome" format](https://github.com/sindresorhus/awesome). ## Motivation -{{Why are we doing this? What pain points does this resolve? What use cases does it support? What is the expected outcome? Use real, concrete examples to make your case!}} +OpenMage's readthedocs has some basic info about the project and a list of modules/extensions, but it doesn't look very modern, the navigation is not really quick and most of all it has [almost zero contributions](https://github.com/OpenMage/documentation/pulls). +This RFC aims to re-create the same "concept" with a different tool, which is considered a de-facto standard (the awesome format) which would provide a more modern look, an easier way for people to interact and contribute and overall a better image for OpenMage. + ## Detailed Explanation -{{Describe the expected changes in detail, }} +Every developer is used to the awesome format, it is widely used for every kind of topics. +The look and feel is the standard GitHub's markdown formatting, which is clean and modern and "standard". +When developers come across an "awesome" repository they know they can contribute easily just by adding a line to a list, so it's gonna be much easier that people will contribute to the list. -## Rationale and Alternatives - -{{Discuss 2-3 different alternative solutions that were considered. This is required, even if it seems like a stretch. Then explain why this is the best choice out of available ones.}} - -## Implementation +Removing openmage.readthedocs.io we would also spare hosting costs/resources (which somebody is not paying/offering), which is a good thing since wasting resources is never good. Not relying on a hosting donation also allows OpenMage to be even more independent. -{{Give a high-level overview of implementation requirements and concerns. Be specific about areas of code that need to change, and what their potential effects are. Discuss which repositories and sub-components will be affected, and what its overall code effect might be.}} +**Why is people not contributing to openmage.readthedocs.io?** -{{THIS SECTION IS REQUIRED FOR RATIFICATION -- you can skip it if you don't know the technical details when first submitting the proposal, but it must be there before it's accepted}} +- since it looks like a website, you (as a contributor) think it's gonna be difficult to contribute, maybe I'll have to read some HTML code and respect certain formatting rules that I don't know, nmaybe github is not the right place because maybe the entries are stored in a database... this kind of psycological processes. +- In order to know what to modify when creating a PR, you've to go to https://github.com/OpenMage/documentation and understand the folder/file structure, which is not hard but for sure way harder than an "awesome" format. There's some python code, a .bat file, mixed stuff not everybody wants to read in order to understand how to contribute. -## Prior Art - -{{This section is optional if there are no actual prior examples in other tools}} - -{{Discuss existing examples of this change in other tools, and how they've addressed various concerns discussed above, and what the effect of those decisions has been}} +## Rationale and Alternatives -## Unresolved Questions and Bikeshedding +There is an alternative, which is to work on the openmage.readthedocs.io repository and website to make it better looking and easier to contribute to. But I don't think we have the manpower for that and the end result still wouldn't loo as "standardized" as the "awesome" format. -{{Write about any arbitrary decisions that need to be made (syntax, colors, formatting, minor UX decisions), and any questions for the proposal that have not been answered.}} +## Implementation -{{THIS SECTION SHOULD BE REMOVED BEFORE RATIFICATION}} +1. Since [this Awesome OpenMage](https://github.com/fballiano/awesome-openmage/) already exists (although it's far from being complete) my suggestion is to fork it under the OpenMage main account (in order to have it as github.com/OpenMage/awesome-openmage) and continue from there. +2. Remove all the content from openmage.readthedocs.io and just implement a 301 redirect to the awesome-openmage repository. +3. Link the awesome-openmage in the main repo's README file (and in the openmage.org website) for easy finding. From f4a8c82b0cbaee2ec87ae4334b5c9e8c4011be50 Mon Sep 17 00:00:00 2001 From: Fabrizio Balliano Date: Wed, 4 Jan 2023 13:25:13 +0000 Subject: [PATCH 3/4] typo --- draft/0000-migrate-readthedocs-to-awesome-format.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft/0000-migrate-readthedocs-to-awesome-format.md b/draft/0000-migrate-readthedocs-to-awesome-format.md index 9212427..02c9587 100644 --- a/draft/0000-migrate-readthedocs-to-awesome-format.md +++ b/draft/0000-migrate-readthedocs-to-awesome-format.md @@ -20,7 +20,7 @@ Removing openmage.readthedocs.io we would also spare hosting costs/resources (wh **Why is people not contributing to openmage.readthedocs.io?** -- since it looks like a website, you (as a contributor) think it's gonna be difficult to contribute, maybe I'll have to read some HTML code and respect certain formatting rules that I don't know, nmaybe github is not the right place because maybe the entries are stored in a database... this kind of psycological processes. +- since it looks like a website, you (as a contributor) think it's gonna be difficult to contribute, maybe I'll have to read some HTML code and respect certain formatting rules that I don't know, maybe github is not the right place because maybe the entries are stored in a database... this kind of psycological processes. - In order to know what to modify when creating a PR, you've to go to https://github.com/OpenMage/documentation and understand the folder/file structure, which is not hard but for sure way harder than an "awesome" format. There's some python code, a .bat file, mixed stuff not everybody wants to read in order to understand how to contribute. ## Rationale and Alternatives From 953623a61dfba086c32f399eb4d48e184aee87ba Mon Sep 17 00:00:00 2001 From: Fabrizio Balliano Date: Wed, 4 Jan 2023 14:20:44 +0000 Subject: [PATCH 4/4] implemented elidrissidev suggestiong --- draft/0000-migrate-readthedocs-to-awesome-format.md | 1 + 1 file changed, 1 insertion(+) diff --git a/draft/0000-migrate-readthedocs-to-awesome-format.md b/draft/0000-migrate-readthedocs-to-awesome-format.md index 02c9587..7fff04b 100644 --- a/draft/0000-migrate-readthedocs-to-awesome-format.md +++ b/draft/0000-migrate-readthedocs-to-awesome-format.md @@ -32,3 +32,4 @@ There is an alternative, which is to work on the openmage.readthedocs.io reposit 1. Since [this Awesome OpenMage](https://github.com/fballiano/awesome-openmage/) already exists (although it's far from being complete) my suggestion is to fork it under the OpenMage main account (in order to have it as github.com/OpenMage/awesome-openmage) and continue from there. 2. Remove all the content from openmage.readthedocs.io and just implement a 301 redirect to the awesome-openmage repository. 3. Link the awesome-openmage in the main repo's README file (and in the openmage.org website) for easy finding. +4. Link the awesome-openmage in the main awesome repository at https://github.com/sindresorhus/awesome