Check out Alistair's suggestions re. managing the development process

[magnusmanske]

(email 19/07/2018 14:48)

[podpearson]

Alistair's suggestions were as follows:

In terms of managing the development process, how about the following...

• Create a github repo for the fits source code and documentation (you all know I love github)
• On the github repo, create a milestone for the first release
• Capture the work to be done for the first release as a series of issues, tag them with the milestone
• (Could also capture any future work as issues but don't tag them with the milestone, so it's clear what's in scope for the first milestone and what isn't)
• Move source code into the repo.
• Move documentation into the repo. Suggest using markdown files, these render nicely on github.org and are easy to edit and also diff and review in PRs.
• Use pull requests for further work to documentation and/or source code, tag in relevant people so they have an opportunity to comment/review before things get merged (probably more important for documentation than code, but PRs are a good habit to get into in general)
• Decide the release process (i.e., how do you version and release the source code? how do we install/update the code? could be very simple, e.g., use git tags, but worth knowing how code versions will be tracked).

[magnusmanske]

Turning this into a checkbox list:

• [x] Create a github repo for the fits source code and documentation (you all know I love github)
• [ ] On the github repo, create a milestone for the first release MVP doc
• [ ] Capture the work to be done for the first release as a series of issues, tag them with the milestone MVP doc
• [x] Move source code into the repo.
• [x] Move documentation into the repo. Suggest using markdown files, these render nicely on github.org and are easy to edit and also diff and review in PRs.
• [ ] Use pull requests for further work to documentation and/or source code, tag in relevant people so they have an opportunity to comment/review before things get merged (probably more important for documentation than code, but PRs are a good habit to get into in general) maybe after MVP release, too cumbersome right now
• [ ] Decide the release process (i.e., how do you version and release the source code? how do we install/update the code? could be very simple, e.g., use git tags, but worth knowing how code versions will be tracked).

[magnusmanske]

Not sure about that milestone. Would that be an "issue"? Can do that.

[podpearson]

See https://help.github.com/articles/about-milestones/. I've not used milestones before so are not familiar with them. If you're still unclear about what @alimanfoo is suggesting after reading that page, perhaps follow up with him.

[alimanfoo]

A milestone is basically just a special type of label that you can attach to issues and PRs. I usually create a milestone for each release. So it's just a way of saying, here are all the issues I plan to address in the next release. You can also manually order the issues within a milestone, e.g., to reflect priority.

Regarding PRs, I can understand if you want to keep development process simple for now, but FWIW the overhead of creating a PR is really very small, and PRs are a really nice way to communicate and create a visible record of things that are changing. Everything I do in every github repo I work in goes in via a PR, even small stuff. If you want someone to review a PR then you can request a review, but you can also just create a PR and then merge it without a review. E.g., in some projects I work in, it's common to make a PR just as a way of communicating changes to other team members, but then say something like "merging soon if no comments" and merge after a few hours or a day if no-one objects. Even if you merge straight away, the PR is still a nice way to create a record of changes.

So the workflow goes like, (1) decide to start work on some task, (2) create a branch for that work, (3) do work and commit changes to the branch, (3) push branch to remote, (4) make a PR from the branch to master, (5) merge the PR.

[magnusmanske]

I'll do the milestone, sounds useful and straightforward enough.

As for PRs, I'll hold off for now, while it's basically just me checking in and running code. I will switch to PRs eventually, probably after MVP is "official".