Update Documentation and App Service Status

[wini3d]

Update the documentation to avoid confusion particularly the App service.

Edit: supposed to be a question, but found the answer..

[VincentTam]

Related: #293

[sukiletxe]

The problems with the current documentation are as follows:

• Old unusable reference to staticmanapp
• No reference to other unofficial public instances
• No reference to v3 (I am using dev, so maybe this didn't get rolled to API)
• No reference to other configurations (GitLab pages)

As @VincentTam summarised in #306, there are many use cases now, but this should be documented somehow. Does anybody have collaborator access to this repo? @eduardoboucas , could you please give it to someone interested? (for example, I could try documenting this, given the many pointers in these issues)

[deadlydog]

I agree that some other peeps should be given Contributor access. I love that you created this @eduardoboucas , but it seems you haven't been able to keep up with the demand on reviewing/accepting PRs and updating the documentation. That's totally understandable, we all have our own lives and supporting free open source projects out of the goodness of your heart can't always take priority. That said though, it would be nice if others could help out. I know @VincentTam has been an excellent resource in responding to issues and making code changes, so he would be a good candidate I think.

[eduardoboucas]

I’m really sorry that I haven’t been able to keep up with the issues and feature requests. You’re right that life gets in the way, but I should’ve done better as a maintainer.

I’m more than happy to give collaborator access to whoever wants to take the helm.

[eduardoboucas]

@VincentTam is it okay if I add you as a collaborator?

[deadlydog]

@alexwaibel might be another good contributor candidate @eduardoboucas

[alexwaibel]

Yeah, I would be happy helping out on this project if possible. I haven't made any contributions except opening an issue but I'm a fairly established developer. I'm not sure how much time I can devote as I'm nearing the end of am internship but I'd be happy to try.

[eduardoboucas]

Thank you, @alexwaibel. I've added you as a collaborator.

I'm happy to assist you in any way you need – showing you around the code base, reviewing PRs, etc. Just let me know.

[alexwaibel]

Thanks @eduardoboucas! I'd definitely appreciate another set of eyes on PRs

[eduardoboucas]

Absolutely. Just add me as a reviewer and I should be able to go through the code in a day or two.

[alexwaibel]

@eduardoboucas and others who have been using this service, I'm thinking of reverting master to commit 9ce2c48. I'm thinking this is our best shot at a working revision as it was the last commit to pass a travis build. It seems that all but one test case passes so this should be a much more stable foundation than the current master which fails many test cases even after I've tinkered with it for a day or two.

Does anyone disagree with this plan? I don't want to revert functionality that someone is relying on but I find it hard to image many people are using the current revision anyway.

[alexwaibel]

Working through the v2 github token auth flows now. Have been using a postman collection to test each endpoint so hopefully afterwards I can get postman to generate some basic documentation for the time being. In the future I hope to have a more robust system, perhaps using Swagger.

[VincentTam]

@VincentTam is it okay if I add you as a collaborator?

Sorry for late reply. I'm glad that Alex Waibel has taken the offer. Thanks again for great project! I'm looking for projects in data analysis, and it's great to see enthusiastic node.js developers here.

[alexwaibel]

This has been partially resolved with #319 and the shift to suggesting users deploy to Heroku. A "Deploy to Heroku" button was added to the README to ease this transition. I still need to dig through the Staticman website and update some of the documentation there so I'll leave this issue open for the time being.

[ousia]

I don’t know whether I should open a new issue. I’m explaining the question here and let me know whether I should open a new issue.

Would it be possible that Staticman could be deployed (also with GitLab Pages) as easily as explained in https://utteranc.es/?

Many thanks for your help.

[alexwaibel]

@ousia the link you provided appears to use a public instance of utterances. We do not offer a public Staticman instance so this same setup cannot be achieved as far as I'm aware. The option of deploying a private insurance to heroku should work fine for Gitlab Pages, though I have not tested it out myself.

[ousia]

@alexwaibel, many thanks for your reply.

I’m afraid I’m only an average computer user and I don’t have the knowledge to understand the problem you describe.

Would it be feasible to provide a public instance of Staticman or is this out of question?

Many thanks for your help.

[alexwaibel]

@ousia as a community run project, we do not have the resources to meet the demand placed on any public instance. It is however quite feasible to host your own free instance. A good write-up about this process can be found here.

[willymcallister]

I wrote up my own experience to deploy an instance of Staticman at Heroku... https://spinningnumbers.org/a/staticman-heroku.html

It has a bit of 'theory of operation' as well. This could benefit from peer review. I'm happy to entertain comments, answers to questions, or pull requests with improvements.

[VincentTam]

Would it be possible that Staticman could be deployed (also with GitLab Pages) as easily as explained in https://utteranc.es/?

@ousia Excuse me for my late reply. The answer to your question is a clear no. The idea is simple and straightforward: in Utterances, you only need one-line of code to get this work. The procedures for Staticman are more complicated, as it is, by nature, a node.js app that converts an HTTP request into a Git commit/PR on your remote GitHub/GitLab repo. Since it consists of more steps, the chances for making mistakes are higher, the setup is certainly more complicated than popular centralized commenting systems. The minimum working simple is https://gitlab.com/ntsim/test-staticman (requires a GitLab account to view).

However, the hard work comes with a reward: the possibly to own your comments, and do "whatever the fork" with it. You may create a couple of branches (so that your git log graph would look like a fork) and test some features. For example, I tested markdown preview with showdown & how it's working KaTeX for instant math rendering, so as to bring out a commenting system allowing math rendering.

[alexwaibel]

Big documentation PR to resolve this up now on the docs repo!