Mega-Task: Documentation for developers

[praeducer]

Sub-tasks:

Higher Priority (by end of 2022)

• [x] Onboarding: https://github.com/trendscenter/coinstac/issues/1417

Lower Priority (early 2023)

• [ ] Automate COINSTAC setup process for new developers - https://github.com/trendscenter/coinstac/issues/1397
• [ ] Requirements analysis
• [ ] Document current functionality
• [ ] Code structure / file / file group descriptions: as a developer I know where to start and how to contribute
• [ ] How components/services interact and communication
• [ ] Architecture / system design descriptions - see "architecture" label in github issues
• [ ] Local environment setup documentation
• [ ] Cloud deployment documentation for the back-end
• [ ] GSU server deployment documentation for clients
• [ ] How back-end services communicate to each other
• [ ] Update https://github.com/trendscenter/coinstac/blob/master/SETUP.md: to operate on production you dont need npm run start but need npm run watch in coinstac-ui but also need to run npm run switch:prod in the top level directory

[praeducer]

Really rough notes from when @dylanmartin, Caleb, and I first setup COINSTAC on our local machines: Improve_documentation_and_setup_process_in_COINSTAC_repo.pdf

[praeducer]

Related tasks:

1397

[BluntBSE]

Here I am documenting issues encountered in my attempt to install and run Coinstac per the instructions provided in Setup.md.

1. Was not able to install windows-build-tools due to a hang while installing python 2.7. Per recommendation about this being deprecated (npm has build tools now), I just installed lerna globally, which allowed me to proceed.

2. Got to npm run start, and ran into issues with coinstac-api-server & sleep. Attempted to in stall packages in coinstac-api-server again. Continued to get issues related to searching for a missing 'compat' module.

[dylanmartin]

SETUP.md was linking to the MRN repository. I just updated the documentation and pushed. https://github.com/trendscenter/coinstac/commit/7441656ff3a742db92e7c70108eb0f49c5fdb83a

[BluntBSE]

@praeducer @dylanmartin - I managed to get the Electron Application running, though I now receive a "connection refused" error, in the screenshot attached. Looks like an error with webpack or the local server (started by Electron?) (bundle.js not found). I haven't used Electron so I don't understand the context here of what might need fixing. Mosquito appears to be running without issue.

Question about the installation instructions: is "windows-build-tools" still necessary? The instructions use node, and WBT itself suggests it's deprecated if you have node installed. I had trouble get windows-build-tools to even install (and many other people do too), but was able to proceed with installation just by installing lerna. I am using Windows 11.

Would it be appropriate to update the instructions to use lerna? If so, may I try my hand at making a pull request? I'd love to understand what else windows-build-tools is used for, and if my OS is why I got away with using lerna alone.

[BluntBSE]

FWIW bundle.js exists at "C:\Users\ramne\Desktop\COINSTAC1\coinstac\packages\coinstac-ui\build", which I assume is what electron is looking at based on the yaml.

[praeducer]

@BluntBSE looks like the team is considering giving you write access for pull requests. We'll report back!

[dylanmartin]

@BluntBSE did you run npm run start from your console before launching the debug process?

[BluntBSE]

@dylanmartin I did indeed. The only deviation from the instructions was that fact that I did not install windows-build-tools, but only lerna.

[BluntBSE]

Update to the above: My connection refused errors were tied to an obscure NPM installation issue on my end. Dylan and I have discussed some updates to make to the installation process, however, which I will document in a pull request.

[dylanmartin]

@praeducer @rssk Here are some questions we should answer: Should we move SETUP.md out of the code repo and into the wiki? If so, should all readmes be pulled out into the wiki? Should any documentation live in the code repo?

https://docs.github.com/en/communities/documenting-your-project-with-wikis/about-wikis

It looks like the github docs suggest having both READMEs in the code repos as well as wiki pages for longer form content

By default, outside contributors cannot edit wiki content - a weakness compared to documentation in the repo - but it looks like that can be changed.

[dylanmartin]

@rssk @praeducer What are the next areas we should focus on with documentation?