IRNAS/irnas-projects-template

[Feature Request/RFC] - Contents of Template for GitHub projects

Closed this issue ยท 17 comments

Context

GitHub repo templates are an easy and quick way to set up a new repository no matter if the repository is meant for software/firmware development or for documentation.
It should provide a common set of boilerplate components (structure, issue templates, changelog, GitHub actions workflows), etc.., that make your life easier.

Note that this is a very general project template, if needed templates for specific purposes (React, Zephyr, etc..) can be created.

Contents of the project template

What I want the template to contain:

  • Basic workflows for release automation as described here
  • An empty CHANGELOG.md file
  • .gitignore with some common excludes (@vid553 I did not include anything for React projects. I think that it's better if this is done separately in a different template. Is that ok, or should it be included here?)
  • Two branches - master and dev, where the latter is the default branch. This can easily be transferred to the new project.
  • Pull request template
  • Issue templates for Bug reports, Feature Requests and Requirements.
  • A common set of issue labels that can be extended.

The above list of things is already contained in this repo (I did it recently). I now require some feedback on specific topics.

Pull request template

Found here Select to view it in raw form as it contains comments that are not visible in preview mode.

Do this PR template requires too much from the code author? Is it missing something?

Issue templates

Found here, again use raw view for templates.

I envision the Feature Request template to be the one used most often, it follows the convention that was established in the Aptar project.
@LukaBanovic @SloMusti (and anyone else) do you want to see something more/else in the Feature Request template?

The requirements template comes from the Pacsana project. I am not sure if we need it...

Issue labels

With labels, you can quickly communicate the contents and status of an issue.

I have created a simple set of labels, you can check them by going to the Issues->Labels page.
I am not particularly tied to the current selection. I have seen this project: https://github.com/abdonrd/github-labels and I have to say that I quite like the format.

Question for you:

  • Did I miss some common labels that you often use and consider general enough to be in this template?
  • Would you be up for using the label setup described in the link?

Feedback

All comments and opinions are welcomed.
Did I miss something?
Would you like me to include something in the template that you often use/need?

I propose the following additions to .gitignore:
#8

Pull request template

  1. I think the checklist should be expanded with some more items - in the sense that the developer could use the checklist while implementing the feature/fixing the bug to not forget to take any steps. What exactly these bullet points are I'm not sure.
  2. Replace Fixes # with Closes #, since the issues are not always bugs, but can pe new features or similar.

Issue labels

I like the distinction on type, status, and priority.

  1. What is the difference between type: enhancement and type: feature request
  2. Should there be a label for "ready" and "not ready" (kanban style), or will we manage what issues are currently being worked on somewhere else?

Otherwise, this is a great starting point for specific templates later on! Good work!

I merged #8.

  1. I think the checklist should be expanded with some more items - in the sense that the developer could use the checklist while implementing the feature/fixing the bug to not forget to take any steps. What exactly these bullet points are I'm not sure.

Something along this lines? https://embeddedartistry.com/blog/2017/08/04/a-github-pull-request-template-for-your-projects/
I initially wanted to keep this short for purposes to be fast, however I am not against something like the above template demonstrates.

  1. Replace Fixes # with Closes #, since the issues are not always bugs, but can pe new features or similar.

I agree.

  1. What is the difference between type: enhancement and type: feature request

I understand that type: enhancement is used to label work on already exiting piece of functionality/documentation/etc.
type: feature request is used for new, non-existing things.

Should there be a label for "ready" and "not ready" (kanban style), or will we manage what issues are currently being worked on somewhere else?

If we decide for label style described in the link that It think that status field should match to the kanban columns: backlog, ready, in progress, validation, done. Or something similar.

@MarkoSagadin I really like the extended checklist from embedded artistry. I also like the type of change and testing sections.
This will force us to be more thorough - although rules around testing (and writing tests) must be determined first probably.

I understand that type: enhancement is used to label work on already exiting piece of functionality/documentation/etc.
type: feature request is used for new, non-existing things.

I feel like a lot of "new" features we do also require changes in existing functionality. Would such a task then get both labels?

If we decide for label style described in the link that It think that status field should match to the kanban columns: backlog, ready, in progress, validation, done. Or something similar.

That would be cool, ok, but we also require these labels:

  • needs information,
  • won't do/fix
  • can't reproduce
  • on hold - for cases when you are working on something but have to move on to another project for a while. Or the issue is no longer as important and other things must be done first.

@MarkoSagadin I really like the extended checklist from embedded artistry. I also like the type of change and testing sections.
This will force us to be more thorough - although rules around testing (and writing tests) must be determined first probably.

I agree, I can pick up some ideas from there. Testing is a separate discussion.

I feel like a lot of "new" features we do also require changes in existing functionality. Would such a task then get both labels?

If possible I would prefer that each ticket can get only one label per possible type, status, priority, etc... I think that in that case we are forcing that a single issue focuses on a single aspect of something. type:epic is an exception here of course.
Maybe type:enhancement and type: new feature would be better choices?

I think that all labels that you listed are a good addition.

Issue template

I like that you simplified the issue template since we are most of the time not filling in most of the sections there.

PR template

<!--- Check items that you fullfilled, strikeout the ones that do not apply and write why --> - it would be nice to have an example for this commend below, for easier understanding.

I think After-review steps section should be marked as optional.

Project template

Agree on the separate template from React and RN projects with a separate .gitignore.

Labels

If we decide for label style described in the link that It think that status field should match to the kanban columns: backlog, ready, in progress, validation, done. Or something similar.

I think this is not necessary. We have the kanban for that.

I like the above mentioned repo with the labels there.

@vid553

- it would be nice to have an example for this commend below, for easier understanding.

Something like below, strikeout is done with tildas?

Checklist

  • Source code documentation for all newly added or changed functions was added/updated.
  • All customer facing technical documentation was updated.

Example strikeout-
- [ ] All customer facing technical documentation was updated. - This PR introduced only internal facing changes.


I think After-review steps section should be marked as optional.

It can be marked as optional, but in what case would you not need it?

I think this is not necessary. We have the kanban for that.

Such labels give an information about issue status when viewed from issues tab for a specific project. I consider this a valuable info. This can also be automated, so labels do not need to be added/changed manually, but they change when you move them between kanban columns.

Something like below, strikeout is done with tildas?

Sure.

It can be marked as optional, but in what case would you not need it?

If you're the only one working on a specific project, the automation will handle that or when it doesn't matter.

Such labels give an information about issue status when viewed from issues tab for a specific project. I consider this a valuable info. This can also be automated, so labels do not need to be added/changed manually, but they change when you move them between kanban columns.

Why not use kanban view for that? There it's more clear, also you can see the issue status written in the issues view (on the right side, under project).
I am not against using this, just think it's not necessary and will clutter the view since each issue will already have other labels. Maybe mark this as optional?

I would really like if we could have only a few labels for each issue and avoid this happening to us:
slika

It can be marked as optional, but in what case would you not need it?

If you're the only one working on a specific project, the automation will handle that or when it doesn't matter.

I understand, it makes sense, I will make it clear in the comment.

Such labels give an information about issue status when viewed from issues tab for a specific project. I consider this a valuable info. This can also be automated, so labels do not need to be added/changed manually, but they change when you move them between kanban columns.

Why not use kanban view for that? There it's more clear, also you can see the issue status written in the issues view (on the right side, under project).
I am not against using this, just think it's not necessary and will clutter the view since each issue will already have other labels. Maybe mark this as optional?

We had an offline discussion for this: status labels won't be used as they are replaced by kanban status functionality.

I would really like if we could have only a few labels for each issue and avoid this happening to us:

I agree that we should avoid that.

I am thinking that max three types would be enough for us: type, priority, area

area label would be optional and I would provide some basic defaults in the template, however I think that each project should be able to define their own area: labels for whatever needs.

@TjazVracko @vid553 I have updated PR template in this commit 3def94f, it addresses your requested changes.

I think that PR template is good for now, any mentions of tests are still missing, but like I said this is topic for the next time.

@MarkoSagadin This is great.
I would just add a link to our guidelines in the first item of the checklist

yes? no?

@TjazVracko good idea, I have added a new commit.

@LukaBanovic @SloMusti I would be happy if you two can give some feecback as well.

After issue labels are created, this issue can be considered as done.

@MarkoSagadin I like the approach, there are a few things on my mind.

A lot of the process-oriented things related to pure coding and making your jobs easier do not influence me in any way whatsoever. For these, if you guys as developers find this useful, I approve it. This is not something that our customers will be interacting with.

I also know for sure that a lot of issues for example won't end up following this structure at all if we continue to use them as a brain dump like we sometimes do now. We now talk about something in person and then someone sits down and briefly describes the issue just enough that the person remembers what we talked about. I don't remember this blocking us at any point so far in any way. Especially this is going to happen when we don't work with a well-structured requirements documentation (which is often at IRNAS).

I like your effort a lot and I think it is the right step! I just want to stress the importance of being careful about when you reach point of diminishing returns. IMO, issues must be good enough, but not more than that. Good enough is good enough here.

Good job!

@LukaBanovic I am happy that you agree with the approach. I have some counterpoints for you to consider.

A lot of the process-oriented things related to pure coding and making your jobs easier do not influence me in any way whatsoever.

I see GitHub Issues and GitHub Projects (the beta version) as a digital communication channel between us and you and other Luka. Putting some structure in place is going to make navigation and try to understand current state of the project a much less cognitive task.

This is not something that our customers will be interacting with.

Some of our customers already do have GitHub access and they can open new issues. Giving them some guidelines on how to structure their wishes, feature requests, bug reports, etc. is going to make their input more valuable and our response to it better.

I also know for sure that a lot of issues for example won't end up following this structure at all if we continue to use them as a brain dump like we sometimes do now. We now talk about something in person and then someone sits down and briefly describes the issue just enough that the person remembers what we talked about.

I agree with you that issues are currently mostly used as a place for brain dump. It is ok to do that in the moment (I mean you do have to write down stuff somewhere), however the usefulness of a such issues quickly diminishes over the time, as you forget why such change was introduced (and other plethora of similar questions). And it makes such kind of issues not useful for the other people that lack understanding of your context.

I see that my coworkers are slowly starting to use this think & write first, then implement approach, which is a good engineering/ risk management practice from the point that is easier/faster to edit text than code.

I like your effort a lot and I think it is the right step!

Thank you ๐Ÿ˜ƒ

I just want to stress the importance of being careful about when you reach point of diminishing returns. IMO, issues must be good enough, but not more than that. Good enough is good enough here.

You are right! I agree that adding more process, required steps just for their own sake does not help.

Additionally, I we can (and we should) continuously improve this template. We need to check-in on this some months later and figure out what is being used and what is not and throw the useless stuff away.

I agree. Having a structure that is handy enough to follow is good news for everybody. Just be careful not to make it too cumbersome. But that will show itself for sure I guess with runtime.

I approve.

I have added discussed changes to the labels and the templates.
Our guidelines now contain a section related to the usage of the GitHub Labels:https://github.com/IRNAS/irnas-guidelines-docs/blob/dev/docs/github_projects_guidelines.md#github-labels-management-%EF%B8%8F