Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Moving CONTRIBUTING.md and DEVELOPING.md to wiki pages #4480

Closed
3 tasks done
nhthn opened this issue Jul 7, 2019 · 7 comments
Closed
3 tasks done

Moving CONTRIBUTING.md and DEVELOPING.md to wiki pages #4480

nhthn opened this issue Jul 7, 2019 · 7 comments
Assignees
Labels
comp: project docs READMEs, info on contributing, etc. enhancement

Comments

@nhthn
Copy link
Contributor

nhthn commented Jul 7, 2019

Motivation

our developer documentation is split in a few different places:

this fragmentation is confusing and makes the docs harder to edit effectively, especially with the in-repo markdown files cross-referencing the project wiki.

a quick check of the history of CONTRIBUTING.md and DEVELOPING.md shows that they are not often edited compared to the wiki pages. i attribute this to the amount of time it takes to open up a pull request and go through the review process. it's just more convenient to edit the wiki directly, and that's why most of our dev docs have gone there.

furthermore, development processes are not really specific to the SC version, so keeping them embedded in the git repo history isn't necessary.

this is motivated by recent efforts to help with onboarding new code reviewers, where there's been a lot of confusion due to lack of project documentation. the first step is to make them more convenient to write and edit.

Plan for Implementation

i will do the following:

  • migrate all project docs to the wiki
  • edit CONTRIBUTING.md and DEVELOPING.md to point to the new location
  • modify the issue, pull request templates, README, and website to also point to the new location
@nhthn nhthn added enhancement comp: project docs READMEs, info on contributing, etc. labels Jul 7, 2019
@mossheim
Copy link
Contributor

mossheim commented Jul 9, 2019

a quick check of the history of CONTRIBUTING.md and DEVELOPING.md shows that they are not often edited compared to the wiki pages. i attribute this to the amount of time it takes to open up a pull request and go through the review process. it's just more convenient to edit the wiki directly, and that's why most of our dev docs have gone there.

👍

furthermore, development processes are not really specific to the SC version, so keeping them embedded in the git repo history isn't necessary.

👍

migrate all project docs to the wiki

what is included in "all project docs"?

other than that all sounds good to me, thanks!!

@nhthn
Copy link
Contributor Author

nhthn commented Jul 9, 2019

what is included in "all project docs"?

DEVELOPING.md, CONTRIBUTING.md, and anything worth salvaging from the "development" section of the supercollider website

@mossheim
Copy link
Contributor

mossheim commented Jul 9, 2019

awesome, let's do ih

@nhthn
Copy link
Contributor Author

nhthn commented Jul 9, 2019

sick

@nhthn
Copy link
Contributor Author

nhthn commented Jul 21, 2019

alright check it out, i moved CONTRIBUTING.md to become the "Guide for New Contributors," did some major updates to the out-of-date parts, and broke off the pull requests part to its own page. some further revisions are necessary, but at least they're way more convenient to edit now: https://github.com/supercollider/supercollider/wiki

DEVELOPING.md is now the "Developer Reference". it is way too long and i intend to split it into separate pages.

@brianlheim do the names "Guide for New Contributors" and "Developer Reference" sound good to you? it will be hard to change them afterward because github's wiki creates the URL based on the page title, so i just want to finalize those

@mossheim
Copy link
Contributor

thanks @snappizz!

Guide for New Contributors sounds good to me. As we discussed on slack I agree it would be a good idea to break up the developer reference page into a couple subpages and then reference them from the main wiki page, which will then become a kind of overview of guides and references.

let's leave this issue open until contributing.md and developing.md have been updated.

@nhthn
Copy link
Contributor Author

nhthn commented Jul 27, 2019

#4503

@nhthn nhthn closed this as completed Dec 8, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
comp: project docs READMEs, info on contributing, etc. enhancement
Projects
None yet
Development

No branches or pull requests

2 participants