MinicraftPlus/minicraft-plus-revived

Planning Contributing Guidelines

Opened this issue · 2 comments

BenCheung0422 commented

Background

Recently, I have added the "Code of Conduct" and the "Security Policy" by #698. That time, I mainly just used the templates or examples from elsewhere, with just little amendments, but we should really have our documents written based on our circumstances and adapt these better in our project structure, while these are quite general and some of the details may not be applicable or useful here. After that, I have started the discussion on Discord specifically for "Contributing Guidelines", without more discussion happened. Along the time, with the growth of this game or this project, it is quite necessary to set some (clear) rules and guidelines to ensure the smoothness of workflows and quality of behaviours. Apart from the project governance rules and the code of conduct, this guidelines would draw clearly what to follows, what to dos, what to not dos, and so on.

For the repository owner, contribution guidelines are a way to communicate how people should contribute.

For contributors, the guidelines help them verify that they're submitting well-formed pull requests and opening useful issues.

For both owners and contributors, contribution guidelines save time and hassle caused by improperly created pull requests or issues that have to be rejected and re-submitted.

Source: Setting guidelines for repository contributors (GitHub Docs)

At the moment, obviously we do not have much clear rules or conventions about how we do in the project, while the practices are still changing, including coding standards and formats, but certainly we should be finalizing these.

Current Tasks

Everything starts from planning. We now need to plan the details on how we write and organize these guidelines, and even what to write. This issue is only for the early stage of the guidelines, and when this is ready, pull request(s) will be opened. Main discussion in the early stage is held either in here or on Discord thread. When both this issue and the corresponding pull request(s) are completed, further discussion shall be made in a separate Discussion thread on GitHub. Then, small changes and questions can be discussed there while major or topical changes can be made into separate issues; pull requests may be made for all such changes.

Planning

While planning, this section may be updated during discussions. In the initial thinking, the contributing guidelines can include several chapters, given that "Contributing" is actually generally a board term, so in fact, other than the "code of conduct" and the "security policy", other rules or practices could be described on it. It will include the areas on GitHub, codebase quality, coding practices, commenting or documentation styles, item naming or translation practices, project management rules/regulation/workflows, etc. There are a lot of ways to structure the guidelines, where some existing examples are:

Then, when we are going to include a lot of content, it may be better to just have a brief description about the entire guidelines in the CONTRIBUTING.md in this repository and details can be on the GitHub.io website.

For topics to write, the currently planned chapters are:

  • Contributing on GitHub (for contributors)
    • Writing Issues (Bug Reports/Feature Requests)
    • Creating Pull Requests
    • Asking Questions
  • Codebase Quality (for maintainer/members)
    • Documentation Styles
    • Codebase Management Practices
  • Code Quality (for all developers)
    • Coding Practices
    • Commenting Styles
    • Item Naming Practices (may be related to Translation)
  • Translation
    • Translation Practices
    • General Rules
  • Project Management (for maintainer/members)
    • Rules/Regulation/Practices
    • Workflows/Practices
    • Label Assignments/Categorization
  • Copyright & License
    • Terms & License (for this project)
    • Copyright Practices (when using other works)
  • Wiki Rules (hosted on the Wiki)

Plans are subject to change. Also, the content may be applicable to all projects under the Minicraft+, should include respective special cases in the respective (sub)projects. Main discussion will be on Discord while minor discussion (in case of non-Team users) and plan changes reflected here.

BenCheung0422 commented

Maybe the Code of Conduct and the Security Policy can be updated at the same time.

BenCheung0422 commented

Added a chapter about "Copyright & License".