Making contributions with GitHub

There are many ways to be a contributor, and we're here to help you on your way! You may:

• Join the discussion and share ideas in our Slack channel and regular TSWG and TATF meetings.

• Raise an issue or feature request in our issue tracker

• Help another contributor with one of their questions, or a documentation review

• Suggest improvements by supplying a Pull Request or opening a Discussion

• Evangelize our work together in conferences, podcasts, and social media spaces.

• Contributing

  • Basic Flow

  • Advanced Flow

  • Commits

  • Branching

  • Tagging

  • Pull Requests

  • Review

• Issues

• Labels

  • Priority Labels

  • Type Labels

  • Status Labels

This section is designed to help you make an edit if you aren't familiar with using GitHub and want to make a change to any repository.

If you're not familiar with GitHub and Git, here are a few simple steps you can use to get going and contribute to the repository without ever touching the command line.

There is also a Video Walkthrough of how to do this if you prefer to learn over video.

1. Fork the repo into your account
   

   
   
   
   

2. Find the file you want to edit. Click the pen tool on the top right of the file to edit it. If you want to add a file, click "Add File". Click "Create new branch". Learn More
   

   
   
   
   

3. Make your changes. When you are ready, click Pull Request on the bar above the file. Then create New Pull Request and choose to set the request to merge to the main branch. Put any information you want to describe your changes in the description, and you're done! Learn More.
   

   
   
   
   

If you've gotten some comments about needing to fix a PR, the process is really simple. You do NOT need to create a new PR.

1. Go to the file in your branch that you want to edit.

2. Click the edit button ( step 2 from when you created the initial edit )

3. Make edits, but this time, instead of creating a new branch, commit to the same branch. Your changes will propagate to the PR.
   

   

4. You may want to re-request a review. Click the sync button to do so:

As a more advanced user, there are a few ways you can manage your GitHub repository:

1. You can use the GitHub web editor

2. You can use GitHub Desktop

3. You can use the CLI

4. Something else! Git is extremely powerful if you want to spend time researching.

• You must sign your commits

• Please try to keep your commit history clean. We do not enforce this but it is encouraged.

• Nobody will work directly on the main branch. All changes must occur over a PR and off the main branch.

• We encourage, but do not enforce branching naming using the following schema: <type>/<description> ex. edit/fix-fig4-label.

• The main branch should always have the latest approved changes

• Custom "feature" branches may be used for special purposes, e.g. for groups to work on a larger section of text

• Branching will occur on forks, not over the main repository. This is to ensure that the main repository is not cluttered with lots of branches from contributors.

• Version tags are used for each release of the document

• Releases should be versioned and if needed, appended with a pre-release tag, e.g. "v1", "v3-RC1", "v4-IIW39"

• Versioning should be simple, only major releases numbered, prepended with letter v. e.g. v1, v2, v3.

• Branch protection rules will exist to not allow a person to directly commit to main.

The below documents some basic best practices for your pull requests.

• Please make sure to ask an editor to review your Pull Request.

• Write descriptive and consistent names.

• Create a clear PR title and description.

• Keep PRs as short as possible

• Try to keep a transparent audit trail of your conversation so people can follow it.

• Avoid rewrites by getting feedback early.

• Request additional reviewers to create dialogue.

• Be precise in your comments about what needs to be fixed.