endless-sky
endless-sky copied to clipboard
endless-sky
The Github Wiki does not provide sufficient tools to maintain it
Location
Wiki
Describe the issue
Github wikis can only either be made editable by those with write access to the repository or by everyone. There is not middle ground where we can pick and choose who can edit the wiki without giving them increased permissions elsewhere on the repository. There is also no way to open a pull request to the repository that developers and reviewers could review and approve. We should look for some alternative to the Github wiki that would allow easier maintenance.
This issue was mentioned in the comments of the development manifesto discussion. https://github.com/endless-sky/endless-sky/discussions/8982#discussioncomment-6348393
Expected content
We should take the existing wiki pages and move them to somewhere where they can be edited local and have pull requests opened for them. We have two ideas for how this could be done:
- Move all of the wiki pages into markdown files in the game's repository. The downside of this is that markdown files viewed form within the repository are more zoomed-in (i.e. less aesthetically pleasing) and lack the sidebar for quick navigation between pages.
- Move the wiki pages to the game's website repository, and update the website's wiki link to link to a home page that lists all the wiki pages. This would provide us more customization options for how the wiki looks, allowing us to keep the sidebar for navigation. We would then replace the wiki page on Github with a link to this new location, and any pull requests to update the documentation would go to the website repo instead of the game's repo.
We could take both approaches as well, couldn't we?
Even if we had some sort of markdown to html converter that took all the markdown files from the game repository and converted them, adding the sidebar, that would let us have them remain easy to access in multiple places.
If the website could pull from the game repo, then perhaps, but we don't want to create multiple places to update.
I prefer the second solution. If someone needs local / offline documentation, they can just download it separately from the base game. Probably most people wouldn't even know where to find the wiki if it was added to the base game.
Both would be best, but only if one could update from the other. Barring that, using the existing website seems like a better option; especially since it can be downloaded for local/offline reference.
However, the existing website has one of the same problems that the current wiki does, in that it can be hard to find if you don't know what you're looking for. I know lots of would-be plugin creators on the Discord, for example, remain blissfully unaware that there even is a development wiki, because it's hidden behind an extra button. The GitHub repo probably has the same problem for plugin creators, since a lot of people don't get the game off GitHub, but at least then they could find the wiki in their files and be aware that it exists, while actual content developers for vanilla could find it more easily. Maybe I'm the exception, but I check ES' GitHub about once every two days, and the website about once every two months.
Perhaps the best solution would be to poll the community and see where most people would be most likely to find the documentation?
I'm dubious about burying it directly in the files, as that's not particularly visible. That being said, what about having it listed as a DLC on Steam? Having an opt-in download that adds an offline version of the wiki to the program folder would both make it easily accessible and much more visible, since there would be a thing sitting there on steam telling people it's there.
That would help, yes.
On another note, if we're doing it on the website, are we going to be keeping the markdown files, or converting them to stripped-down html like the current files?
I'm dubious about burying it directly in the files, as that's not particularly visible. That being said, what about having it listed as a DLC on Steam? Having an opt-in download that adds an offline version of the wiki to the program folder would both make it easily accessible and much more visible, since there would be a thing sitting there on steam telling people it's there.
Might be finicky. People would download it then wonder where to access it. Telling them that it's in their program files might not be helpful for some people... or I might be underestimating them. I think a wiki on the endless-sky.github.io website would be more useful, only that website needs to be more visible because I have trouble finding it without my lazy self typing it out.
I also feel like we should keep things that aren't necessary for the game to function outside of the repository. But I'm still new to GitHub, so perhaps this sort of stuff might be standard practice.
For increasing the visibility of the wiki page, maybe put the link in the Plugin Preference panel or something. Idk how many people actually look at that panel (I don't, even when starting out) but now at least everyone regardless of source for the game would have a way to find out about the wiki.
I also feel like we should keep things that aren't necessary for the game to function outside of the repository. But I'm still new to GitHub, so perhaps this sort of stuff might be standard practice.
That is part of why I suggest the plug-in route. It gives people the choice of whether or not to download it, rather than forcefully bundling it in. That being said, it's not uncommon to have extras (like cosmetic "DLC" like wallpapers or copies of the soundtracks suitable for listening to outside the game; not to mention manuals, to be included in the game installation folder.
As far as that goes, it'd be fun to have a wallpaper DLC pack full of ship scenes.
Just looking through steam, I note that MZ actually has a guide for the game that includes a link to the website, github wiki, and google forums...
Just looking through steam, I note that MZ actually has a guide for the game that includes a link to the website, github wiki, and google forums...
Right. But if you, being a contributor to Endless Sky who has had the most commits to the game repo of any active contributor except Derpy, were unaware of the existence of such a guide before now, it probably has escaped the notice of the vast majority of Steam players... and it still does nothing for those who don't get the game on Steam.
I wouldn't move the whole wiki, but instead create files for each node as a kind of reference without 'fluff' so to speak. Something like the player manual probably doesn't belong in the repo imo? Idk
As for the website, we can add a CI job that we trigger manually when a release is published so that the website can update itself.
I wouldn't judge anything on steam by my awareness of it... I never got into ES via steam, nor do I use ES via steam on a regular basis. I generally just have it installed and run it once in a while to confirm bugs or test out if a new release broke something. I virtually never frequent the discussions or guides or anything.
We could take both approaches as well, couldn't we?
Even if we had some sort of markdown to html converter that took all the markdown files from the game repository and converted them, adding the sidebar, that would let us have them remain easy to access in multiple places.
Like mdBook?
The wiki itself is a Git repository.
git clone [email protected]/endless-sky/endless-sky.wiki.git
You can put the current wiki into a repo with GH actions and push back to the wiki on merge.
With this, you won’t need to figure out extra steps on how to host and the wiki remains where people expect it to be.
The wiki itself is a Git repository.
git clone [email protected]/endless-sky/endless-sky.wiki.gitYou can put the current wiki into a repo with GH actions and push back to the wiki on merge.
With this, you won’t need to figure out extra steps on how to host and the wiki remains where people expect it to be.
I've been working on this recently. Providing an existing, third party action with a token granting write access is undesirable, so once I have an action defined within the repository itself, it'll be more or less ready to go.
@warp-core another option is on-merge an action in the repository itself can fetch the version of the two wikis (the pull request one and the endless sky wiki) and if different push/synchronize them.
It could also be a trigger-able action post-merge.
If mdBook gets used or something else (like jekyll); I think we should create a new repository named manual and have it publish to GitHub pages. Then it would be hosted at the same domain as the website but with a subpath.
For example, https://endless-sky.github.io/manual
We now have warp's wiki-clone repository. Once we provide accessible instructions on how to contribute to it, could we close this issue?
I received an email from @Amazinite asking me to create a new wiki repository a while back; but without any details or information about what was actually wanted, so it didn't happen at the time.
Is what is desired basically just contain the git import from our current wiki? If so, that is relatively straight forward, and I can do it in a few minutes. Or was an explicitly empty repository that could then be used as a workplace for uploading files? It was never made clear.
We would like you to create an empty repository named endless-sky-wiki that we can push to. No initial commit is necessary. The expected default branch should be named master (the default branch for newly created repositories is a setting in the organisation/account, but since there will be no initial commit, there will not actually be any branches yet).
Just to clarify: Do you actively not want the git import of the wiki; or is it merely "not necessary"?
I ask, as it is actually just as fast (from my side) to create one via import as creating an empty one.
Just to clarify: Do you actively not want the git import of the wiki; or is it merely "not necessary"?
I ask, as it is actually just as fast (from my side) to create one via import as creating an empty one.
It would be simpler for me if the repository is empty.
Ah? I'm curious as to why. Worse comes to worse, anything just overwrites what's there, since anything you push would be newer.
I don't know that Git will be able to immediately reconcile the history I want to push. It shouldn't be difficult to resolve, but it'd be an extra step. Given that it makes no difference to you:
I ask, as it is actually just as fast (from my side) to create one via import as creating an empty one.
And might introduce an extra step for me, I don't really see any benefit to doing that.
From my perspective, it makes it clearer that the baseline is the original wiki coming from here and MZ; and makes your changes (if any) visible as changes in the public commit history here. So from a transparency side, I prefer that it starts from where things are now, and your work is, thus, your work being pushed to it.
Thus: If it creates a massive amount of work, ok, skip it. If it's just one extra step this one time, then let's keep the transparency and visibility of starting from the current ES wiki and work from there.
From my perspective, it makes it clearer that the baseline is the original wiki coming from here and MZ; and makes your changes (if any) visible as changes in the public commit history here. So from a transparency side, I prefer that it starts from where things are now, and your work is, thus, your work being pushed to it.
Thus: If it creates a massive amount of work, ok, skip it. If it's just one extra step this one time, then let's keep the transparency and visibility of starting from the current ES wiki and work from there.
The entire history will be present in what I push. I will not be squashing the wiki. Making the entire history easily accessible is actually one of the reasons I wanted to use a separate repository.
And I also note that you say it may add an extra step.
So let's just skip the debate on it, and do it. I'm opting for the import for the above reasons, and you can tell me if that worked, or if the extra step looks too onerous. Worse comes to worse, I delete and recreate a blank one.
Either way, probably end up with the desired result faster than spending an hour discussing relevant merits.
Should be up in a minute or two. I'll assign write permissions once it's up.
Wing Leaders all have write access, each of the patrol groups have triage.
Given the nature of the wiki, I'd say there's a good case to be made that the Writing patrol group should probably have write permissions, and probably the code, too.
And I also note that you say it may add an extra step.
So let's just skip the debate on it, and do it. I'm opting for the import for the above reasons, and you can tell me if that worked, or if the extra step looks too onerous. Worse comes to worse, I delete and recreate a blank one.
I'm not sure one person asking questions and another answering them constitutes a debate.