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.

Sign up for GitHub

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

Jump to bottom

docs: revise contribution guidelines for clarity and inclusivity #1831

Merged
merged 1 commit into from
Mar 29, 2024
Merged

docs: revise contribution guidelines for clarity and inclusivity #1831

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
226 changes: 208 additions & 18 deletions doc/contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,29 +1,219 @@
## Code Structure
# Contributing Guidelines

TODO
Thank you for your interest in contributing to the Go+ project! Your efforts
help us build and improve this powerful language.

## Contributing
Please be aware that participation in the Go+ project requires adherence to our
established [code of conduct](https://github.com/goplus/gop/blob/main/CODE_OF_CONDUCT.md). Your involvement signifies your agreement to comply
with the guidelines set forth within these terms. We appreciate your cooperation
in fostering a respectful and inclusive environment for all contributors.

The Go+ project welcomes all contributors. We appreciate your help!
To ensure a smooth contribution process, this guide outlines the steps and best
practices for contributing to Go+. It's assumed that you have a foundational
knowledge of Go+ and are comfortable using Git and GitHub for version control
and collaboration.

Here are [list of Go+ Contributors](https://github.com/goplus/gop/wiki/Goplus-Contributors). We award an email account (XXX@goplus.org) for every contributor. And we suggest you commit code by using this email account:
## Before contributing code

The Go+ project welcomes code contributions. However, to ensure coordination,
please discuss any significant changes beforehand. It's recommended to signal
your intent to contribute via the issue tracker, either by filing a new issue or
claiming an existing one.

The issue tracker is your go-to, whether you've got a contribution in mind or
are looking for inspiration. Issues are organized to streamline the workflow.

Except for very trivial changes, all contributions should relate to an existing
issue. Feel free to open one and discuss your plans. This process allows
validation of design, prevents duplicate efforts, ensures alignment with
language and tool goals, and confirms design validity before coding.

## Making a code contribution

Let's say you want to fix a typo in the `README.md` file of the
`https://github.com/goplus/gop.git` repository, changing "Github" to "GitHub",
and you wish to merge this contribution into the `main` branch of the upstream
repository.

### Step 1: Fork the upstream repository

First, you need to fork the upstream repository to your own username (or an
organization you own) by following [this guide](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo). Then you can start making your
contributions.

Let's say you've forked `https://github.com/goplus/gop.git` to
`https://github.com/YOUR_USERNAME/gop.git`.

### Step 2: Clone the forked repository

Open your terminal, clone the repository you just forked, and change into the
cloned directory:

```
git clone https://github.com/YOUR_USERNAME/gop.git
cd gop
```

This directory will serve as the working directory in the following steps.

### Step 3: Create a new branch

We recommend that every contribution should have its own branch, and this branch
should be deleted after the contribution is merged into the target branch of the
upstream repository.

First, you need to sync your fork's `main` branch to keep it up-to-date with the
upstream's `main` branch by following [this guide](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork).

Then, you can create and switch to a branch for your contribution:

```
git checkout -b typo main
```

### Step 4: Make the changes

This step is where you'll spend most of your effort when contributing. It
typically takes up the majority of the time needed to make a contribution.

However, in our case, we just want to correct a typo in the `README.md` file,
changing "Github" to "GitHub". So, go ahead and make that change.

### Step 5: Commit and push

After making your changes, you need to commit them:

```bash
git config --global user.email XXX@goplus.org
```
git add README.md
git commit -s -m 'README.md: correct typo "Github" to "GitHub"'
```

The commit message here is very straightforward, but it's recommended to read
the [Commit Messages](#commit-messages) section for crafting better commit messages.

Once you've committed your changes, you also need to push your commit to your
fork on GitHub:

```
git push --set-upstream origin typo
```

### Step 6: Open a pull request

Head to the upstream repository and open a pull request by following
[this guide](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). Your pull request should clearly describe the change you're
proposing and why it's beneficial.

Typically, the title and description of the pull request you open will come from
the first commit message in the branch of your fork. You can modify them if
necessary.

### Step 7: Engage with feedback

Be open to feedback from upstream repository maintainers. They might request
further changes or provide insights that could enhance your contribution.

After making any further changes, simply repeat [Step 5](#step-5-commit-and-push). However, when
committing, it's recommended to use the `--amend` option. This ensures that all
your changes are contained within a single commit, maintaining a linear commit
history. For example:

```
git add README.md
git commit --amend
```

This isn't a strict requirement, though. You can create as many commits as you
like.

### Step 8: Do post-merge cleanup

As mentioned in [Step 3](#step-3-create-a-new-branch), we recommend dedicating a branch to each contribution.
Once a contribution's pull request is [squash and merged](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-commits), the branch should be
deleted:

```
git checkout main
git branch -d typo
git push origin -d typo
```

## Commit messages

Commit messages in Go+ adhere to specific conventions outlined in this section.

A well-crafted commit message looks like this:

```
docs: revise contribution guidelines for clarity and inclusivity

As our project grows, we want to ensure that our community understands
how to contribute effectively and feels welcomed to do so. This update
to our contribution guidelines aims to clarify the process and encourage
more developers to get involved.

Key changes include:
- Simplified the language to make the guidelines more accessible to
non-native English speakers and newcomers to open source.
- Included a step-by-step guide on setting up the development
environment, submitting a pull request, and what to expect during
the review process.
- Added a new section on community standards and code of conduct to
foster a respectful and inclusive community atmosphere.
- Provided clear examples of desirable contributions, such as bug
fixes, feature proposals, and documentation improvements.

Fixes #123

Signed-off-by: John Doe <john@example.com>
```

### First line

The first line of a commit message typically serves as a concise one-line
summary, beginning with the primary component it impacts (e.g., a specific
package). This summary should ideally be brief, with many Git interfaces
favoring a limit of approximately 72 characters. While Go+ is not strict on the
length limit, it's a good guideline to follow.

Think of the summary as finishing the sentence "This commit modifies Go+ to
_____." As such, it does not begin with a capital letter, form a complete
sentence, or diverge from succinctly stating the commit's effect.

After the summary, ensure to separate the main content (if any) with a blank
line.

### Main content

The rest of the commit message should elaborate, offering context and a clear
explanation of the commit. Employ complete sentences and proper punctuation.
Refrain from using HTML, Markdown, or any form of markup language.

Include relevant information, like benchmark data, if the commit impacts
performance.

Adhere to a line width of approximately 72 characters to accommodate Git viewing
tools, except when longer lines are necessary (such as for ASCII art, tables, or
extended URLs).

### Referencing issues

The special notation `Fixes #123` links the commit directly to issue 123 in the
issue tracker. Upon merging this commit, the issue tracker will automatically
mark the issue as resolved.

If you did this, remember to add your `XXX@goplus.org` email to https://github.com/settings/emails.
For commits that partially address an issue, use `Updates #123`. This notation
will not close the issue upon the commit's integration.

What does `a contributor to Go+` mean? You must meet one of the following conditions:
To reference multiple issues within a single commit, list them by appending each
issue number with a comma and a space, such as `Fixes #123, #456`. This indicates
that the commit resolves both referenced issues.

* At least one pull request of a full-featured implemention.
* At least three pull requests of feature enhancements.
* At least ten pull requests of any kind issues.
For cross-repository references, use the full `user/repo#number` syntax, such as
`Fixes goplus/gop#123`.

Where can you start?
### Signed-off-by

* [![Issues](https://img.shields.io/badge/ISSUEs-Go+-blue.svg)](https://github.com/goplus/gop/issues)
* [![Issues](https://img.shields.io/badge/ISSUEs-NumGo+-blue.svg)](https://github.com/numgoplus/ng/issues)
* [![Issues](https://img.shields.io/badge/ISSUEs-PandasGo+-blue.svg)](https://github.com/goplus/pandas/issues)
* [![Issues](https://img.shields.io/badge/ISSUEs-vscode%20Go+-blue.svg)](https://github.com/gopcode/vscode-goplus/issues)
* [![TODOs](https://badgen.net/https/api.tickgit.com/badgen/github.com/goplus/gop)](https://www.tickgit.com/browse?repo=github.com/goplus/gop)
For contributions to be accepted, we mandate that a `Signed-off-by` line, in
accordance with the [Developer Certificate of Origin](https://developercertificate.org/), be included at the
conclusion of each commit message.