algorithm-archive
algorithm-archive copied to clipboard
algorithm-archivists
Implementation of Language specific guidelines
Related closed issues: #152 #18 #12 #25. In my opinion, we should consider adding good practices, links to linter and prettifiers and general styling rules, like using spaces instead of tabs for indentation and how many spaces to each language. But this could be a good place to define a way to contribute in relation to writing the chapter's text, like in #25, as, for now, we have to wait for @leios working on it and there is not a defined way of writing and submitting PR in respect of this.
- [x] Start writing a How to Contribute section
- [x] Make language-specific subsections as we think about them
- [ ] Make a general section for defining common styles and list "Prettifiers" and "linters"
- [ ] Add PR and Issues templates
@lulucca12 I agree. Something like this is useful. Maybe we should have a page for each language in the wiki?
I think a page per language is excessive, unless we're talking about C++ 😛
Fair enough. I know @julianschacher and @Butt4cak3 were both talking about adding more to the How to Contribute section.
I think we should list some TODOS for closing this issue and add them separately, one in each PR. Something like this:
- [x] Start writing a How to Contribute section
- [ ] Make a list of "Prettifiers" and "linters"
- [ ] Make a general section for defining common styles
- [ ] Make language-specific subsections as we think about them
- [ ] Add PR and Issues templates
And we could add more.
I'm currently working on the How to Contribute section, so that will come in the following days. I also thought about PR and Issue templates, the question is, if they scare people and if they provide a real benefit, so that's something to discuss.
I think we should create simple and non-intrusive templates that should be just a way of getting started, for people that face the problem of the blank page, doesn't know how to start making the first issue/PR but not so complex that they feel intimidated.
- [ ] Start writing a How to Contribute section
As Julian already said, he's working on that and I'm also working on a video series on the topic. In addition to that, I did a live stream to show the process and answer some questions, but that one didn't go too well.
- [ ] Make a list of "Prettifiers" and "linters"
- [ ] Make a general section for defining common styles
I'd combine these two. They're so closely linked that it makes sense to first outline the code style and then recommend some linters for it. If possible, we should also add linting configurations to the repository.
Other than that, I agree on these points. You might want to move the checklist to the top post for visibility, @lulucca12.
@Butt4cak3 Do you have a schedule or you do the streams occasionally? I follow you on Twitch and I couldn't watch it. I agree with the idea of streaming the process of contributing to the Archive and I think it should be done by more people.
@lulucca12 I'm not a streamer. I stream things occasionally, when I feel like it. I was thinking about trying the contribution stream thing again because I think it failed in part because it was too spontaneous. If there's a next time, it will be announced somewhere beforehand.
@lulucca12 You can check the first point. The How to Contribute section is being worked on by me.
How to Contribute section: https://github.com/algorithm-archivists/algorithm-archive/wiki/How-to-Contribute and a video playlist by @Butt4cak3 : https://www.youtube.com/playlist?list=PL5NSPcN6fRq2vwgdb9noJacF945CeBk8x
@julianschacher @Butt4cak3 This section is nice, thanks for creating resources for making the contribution more easy for me and for others :smile:
You're welcome; I hope it does help! If you find anything that's unclear, have any questions or suggestions, please let me know.
I think we could close this one, since we have Code style guide and How to contribute
cc @Butt4cak3 @leios @julianschacher
So, what thoughts do you (all) have on them?
As I said before, they can provide useful information, but they might be scary (probably, if they are too heavy, long and/or complicated).
If we can come up with simple and friendly ones however, I think we can add them. It would check a point of this.
As a PR template, I'd suggest something like
[Please write a few words about what this PR does. If it fixes an issue or improves an aspect of the book, please explain what the issue was or why you think your change is an improvement.]
So nothing too formal, but at least a reminder to actually write something into the description. Lots of people just set the title and leave the description empty. That works for very simple PRs, but most of the time it's a good idea to write a sentence or two.
Issue template is quite harder if you want write. Because it might be problem of text, code or anything unrelated.
Howere I agree with @Butt4cak3 that simple PR template with basic description would be sufficient.
If we have a pr template we could also have a bot that then pings a person on the discord according to @julianschacher google doc list. We could also bump a pr after a week or so and ask for changes. etc. Some goes obviously for the issue template thing. If we end up creating both of these templates (+1 for that btw) we should add them to the How to contribute imo.
@Liikt Automatically pinging people, who said that they can review certain languages, would make the google doc list feel like something that obligates people to review stuff. I think we should handle it more like a reference, that can be used manually.
For the PR bump thing: We can use the Stale app for that.
Requesting reviews can be done if you know, the person is only valid/active person, which can do review. If it's not the case, you can just wait, and after few days you request review.
As for me, I requested review from @Butt4cak3 , but he got no notification about that. Stale App looks good.
To be fair, I may have accidentally the notification as read or it was a one-off thing. It was probably human error.
Automatically closing issues doesn't sound like a good idea to me. We have a bunch of old PRs in this project that shouldn't get closed.
I think that autoclosing can be set to like 10000 days or maybe even turned off, but the stale, could help with not progressing PR's which are not marked as WIP
I believe we should implement PR templates for chapter submissions, code submissions, and issues once #493 is resolved.
We are missing a lot of languages in the Code Style Guide, but we are making progress.
