Although markdown files are readable but not have a rich UI. We can enable github pages and add a theme to this repo (everything handled by GitHub on just a single button click) so that documentation looks fresh and intuitive.

Have a look here https://rahulm2310.github.io/documentation/ways-to-contribute.html

Step by step guide for absolute beginners to contribute.

As a beginner,
I need a complete beginner's guide on how to proceed on my first issue,
so that I can break the hesitation that the beginners have which makes them reluctant to contribute.

Required items:

1. A BEGINNER_GUIDE.md file with step by step guide.
2. How to choose the first issue and get it assigned.
3. Step by step git commands for setting repository locally.
4. Creating a pull request.
5. Relevant links to documentation.
6. What to do if get stuck.

Definition of Done

• All of the required items are completed.
• Approval by 1 mentor.

Estimation

12 hours

Description

An initial version of this just needs to contain information about our Zulip. It can include the main streams we use and the project's streams. Explain what each stream is used for.

Adding emojis to each channel could be fun :)

Is your feature request related to a problem? Please describe.

Currently we follow a style of commit similar to one mentioned here. There are many tools that can auto generate changelogs and also this type of convention helps us review the commits if something goes wrong.

Describe the solution you'd like

Setup these tools that will automatically generate change logs.

Additional context

Also explore if these tools can enforce the convention only for maintainers when they merge and not on contributors ( as rebasing can be pretty hard for first timers).

Describe the bug

To Reproduce

Steps to reproduce the behavior:
Update the below:
Change

1. Make sure contributors are respecting the (https://github.com/anitab-org/anitab-org.github.io/blob/develop/CONTRIBUTING.md). If they don't let them know about it: what is missing, what was disrespected?

to

2. Make sure contributors are respecting the (https://github.com/anitab-org/documentation/blob/master/ways-to-contribute.md). If they don't let them know about it: what is missing, what was disrespected?

Expected behavior

Screenshots

Desktop (please complete the following information):

• OS: [e.g. iOS]
• Browser [e.g. chrome, safari]
• Version [e.g. 22]

Smartphone (please complete the following information):

• Device: [e.g. iPhone6]
• OS: [e.g. iOS8.1]
• Browser [e.g. stock browser, safari]
• Version [e.g. 22]

Additional context

Problem

Currently, our Medium Blog is lacking a background image which can make the Blog look a bit boring.
So the idea here is to design an asset that will look good on our Medium Publication.
We want something to enhance the title of the publication.

Be as creative as you want, having in mind the redimensioning of the page, something that can be flattering no matter the size of the page.

You can get the AnitaB.Org Brand Guidelines here in this message.

Current visual

References

• Cover image submission guidelines: https://help.medium.com/hc/en-us/articles/360053012914

Problem

For someone to perform manual testing a web PR, they have to set up the whole project just for it. This can be cumbersome, and difficult for someone not used to deal with setting up coding projects.

Idea

So we wish to have a service that allows us to have Pull Request deploy previews.
This would help majorly testers and developers, to not just review code.
This would look like: having a link per PR that has the latest code of the project plus the code from the PR.

Examples

You can look at this example of a project that has this: https://github.com/thepracticaldev/dev.to
Look in the PRs and you should see they have a check in the bottom with the deploy preview.

Resources

Useful services:

• Netlify - https://www.netlify.com/
• Heroku - https://heroku.com/

Is your feature request related to a problem? Please describe.

Currently projects under anita-org has their own copy of Commit Message Style Guide instructions on wiki page. These pages are redundant because we only need one page that all projects can refer to.

Describe the solution you'd like

Create COMMIT_MESSAGE_STYLE_GUIDE.md template.

Describe alternatives you've considered

NA

Additional context

NA

Describe the bug

It is important to build our technology with inclusive design language in order to foster an inclusive workplace where everyone feels they can belong. In order to achieve this, can we change our branch name from master to main?

To Reproduce

Steps to reproduce the behavior:

1. Go to branches dropdown
2. See master branch

Expected behavior

1. Change branch name from master to main and update in readme here .

Screenshots

Is your feature request related to a problem? Please describe.

Register form on all AnitaB.Org Open source applications need to have common Privacy Policy. At the moment developers getting the content from https://anitab.org/privacy-policy/ and copy paste it to their code if they want to use a pop-up modal. This is prone to content manipulation or errors which makes code review difficult.

Describe the solution you'd like

If we have PRIVACY_POLICY.md in the /documentation repo, developers can use .md parser in their project so that any changes made to this policy will automatically apply to that project. This ensures the policy is up to date and consistent across all AnitaB.Org Open Source projects.

Describe alternatives you've considered

NA

Additional context

I believe the content of the Privacy Policy of the AnitaB above can be used across all projects as indicated in the screenshot below.

Description

We need to be more transparent in some of our goals, in particular, tools that we decided to adopt along the way, but did not write this in a such a public and common place like GitHub.
We want a document that tracks the adoption of such tools. Tools include GitHub Actions for our CI/CD pipeline (instead of Travis CI), use of Docusaurus for our documentation (instead of Google Docs - when possible, and GitHub Wiki)

Acceptance Criteria

• Set goals for the tooling we use
• Add a table with the projects and the tooling adoption

The idea here is to have the first version of the quality assurance guide. In my Office Hour me and @rpattath came up with a plan for it so this should be put into public more accessible document than the "Community Open Session Minutes" document.

Description

@annabauza has clear guidelines for designer collaboration. It would be great if this could be in a public document we can reference to ambassadors while being transparent with the whole community.

Suggestions

This could be a document design.md in the root of the project, or a design folder with a document only dedicated to collaboration guidelines

Describe

There are some grammatical errors in the ways-to-contribute.md and quality-assurance.md files.

Expected Behavior

All of the below mentioned grammatical errors needs to be fixed.

Steps to reproduce

1. Go to ways-to-contribute.md.
2. See errors in the description.

Screenshots

ways-to-contribute.md

quality-assurance.md

Description

As a contributor,
I need information accessible to me about the community (less on Google Drive - more on GitHub),
so that I can learn more about it.

The idea is to post the meeting summaries on here just as we tend to do on Zulip. Therefore making information more transparent and available to people who are not part of our Zulip community.

Acceptance Criteria

Update [Required]

• A new folder called meetings with a markdown file for mentorship-system. Most recent meetings should have the summary on the top. 3 summaries should be enough.

Enhancement to Update [Optional]

• A README explaining briefly the folder contains meeting summaries

Definition of Done

• All of the required items are completed.
• Approval by 1 mentor.

Estimation

1 h

Description

List in a document the many ways people can contribute to our community. Take inspiration from OS Ambassador's document. This is not a blog post, just a list of examples in bullet points, so this is easy to share with newcomers in our community.

Acceptance criteria

• Mention how to contribute to many categories we encourage in the community
• Link to documents within this repository
• Mention the Calendar from the community

Is your feature request related to a problem? Please describe.

Currently projects under anita-org has their own copy of Fork, Clone & Remote instructions on wiki page. These pages are redundant because we only need one page that all projects can refer to.

Describe the solution you'd like

Create FORK_CLONE_REMOTE.md template.

Describe alternatives you've considered

NA

Additional context

Make sure you remove any project specific references.

Description

As a first time contributor,
I need a bot to help guide my first contribution,
so that I can follow this org's contribution guidelines.

Mocks

Acceptance Criteria

Update [Required]

• newIssueWelcomeComment is complete with the correct links to this repo.
• newPRWelcomeComment is complete with the links to the project's stream or topic and the repo's Code of Conduct.
• firstPRMergeComment is complete.

Definition of Done

• All of the required items are completed.
• Approval by 1 mentor.

Estimation

0.5 hours

Is your feature request related to a problem? Please describe.

Projects needs to have one source of truth where they can refer to Design Contribution Guidelines instruction on wiki page.

Describe the solution you'd like

Create DESIGN_CONTRIBUTION_GUIDELINES.md template.

Describe alternatives you've considered

NA

Additional context

• Content for the template can be found here
• Note: remove project specific content

Problem

The current Contributing Guidelines seems a bit more of a grocery list, that I think contributors are bypassing this information. We want to make it easier to contributors

In my opinion, we should have separate sessions for every type of contribution we welcome: coding, manual testing, documentation, etc. Having this, we can provide specific guidelines for each type of contribution.

The idea here is to create a template for CONTRIBUTING.md and share it with the community.

• Example: anitab-org/mentorship-android -> CONTRIBUTING.md
• Ideas by Sakshi shared on Zulip

Tasks

• Create a template for Contributing Guidelines

A feature with clear details about the research done and need for the feature is considered a good feature request.
(keeping this in mind we have to improve the following guidelines)

• First contributions
• Pull requests
• issue labels
• commit messages
  for further details you can visit the doc link mentioned below-
  https://docs.google.com/document/d/1ysCUVb1IuuQykR4d5a22BoIWwafRjw70ctQ3Kkf2SHw/edit
  https://docs.google.com/document/d/1ccY9z46xF6a_tHtd5QcdmrxtEQaw1Mt2PfA-aKUm0gg/edit#heading=h.glme02jzxnqq

(from old title) add contributing guidelines to improve the following features like pull request, first time issues etc.

Add CODE_OF_CONDUCT and REPORTING_GUIDELINES to the root folder of this project.
This is important for having a source of truth about our documentation.

Here's examples you can copy:

• CoC: https://github.com/anitab-org/anitab-org.github.io/blob/develop/docs/code_of_conduct.md
• Reporting Guidelines: https://github.com/anitab-org/anitab-org.github.io/blob/develop/docs/reporting_guidelines.md

Is your feature request related to a problem? Please describe.

Fix grammatical mistakes under this section.

Example

This document lists the many ways you as a member of this community can contribute to our community! You can be a newcomer to the community or someone who is with us for a while :)

Description

There is a typo in the README, the duplicate word in the design guidelines bullet point.

Acceptance Criteria

Update [Required]

• Remove duplicate Contributing word from Design guidelines on README

Definition of Done

• All of the required items are completed.
• Approval by 1 mentor.

Estimation

0.5 hours

Description

As a new contributor,
I need the information about the community to be accessible,
so that I can learn more about the community.

We have this information already in this Google Docs document. Only people who are already acquainted with the community are aware that this exists. So we want to be more transparent about that.

Acceptance Criteria

Update [Required]

• Add new document with content from this program

Definition of Done

• All of the required items are completed.
• Approval by 1 mentor.

Estimation

30 min

Describe the bug

https://github.com/anitab-org/documentation/blob/master/quality-assurance.md
The document is not up to date, for example it does not include bridge-in-tech backend and web, AnitaB forms Backend, and Stem Diverse in the top projects sections which should be added.
It also includes our archived projects in top section and setup instructions which should be removed.

Expected behavior

Include active projects and remove archived projects.

Problem

As of now, if a tester wishes to test an Android PR, they have to run and build the project. This can be cumbersome for a tester.

Idea

Discover a way to produce apks per pull request.

We could research if we are able to do that with a GitHub Action or something like that, to build an APK per pull request. The same way we have an apk generated for most of Android projects.
Example: Android APK from mentorship-android apk branch

Once this is solved, this can be applied to every Android project of ours.

Description

This file ways-to-contribute.md has the text referring to #documentation stream on Zulip. We could have a link to it, like other streams in the same document have.

Why

This helps newcomers reading the document have direct access to the stream

Acceptance Criteria

• Add the link to #documentation stream from Zulip

Description

I want to explain our Open Sessions and make it clear that these:

• are open to anyone to attend
• no need for video camera usage, it's usually audio only
• opportunity to meet some leaders and ask questions and debug together
• may happen on Google Meet or Zoom
• link the calendar in multiple timezones
• ???

Acceptance Criteria

Update [Required]

• Add new document to explain our Community Open Sessions
• Add the document link to Documentation section on the README

Definition of Done

• All of the required items are completed.
• Approval by 1 mentor.

Estimation

0.5

Is your feature request related to a problem? Please describe.

It would be helpful for contributors to know the OS Leaders and their roles on the projects. This way they know who to ping on project specific issue.

Describe the solution you'd like

Create a OS_LEADERS.md doc that shows a table below:

Describe alternatives you've considered

NA

Additional context

List of OS Leaders with their project/role will be taken from the OS Project Pods document which is accessible only to admins and OS Leaders. So, perhaps this issue can only be claimed by an OS Leader.

Problem

As we evolve as a community, we are evolving our open source workflow. Currently we have been trying to add a QA testing step to how we handle pull requests, and this is not yet visually represented. I think this could clear up confusion from new and current contributors.

In the past, we had this open source workflow: http://systers.io/open-source-workflow

Today we have a specific way of assigning labels to define the status of PRs and issues. We want to have this visually represented.

To help understand some of our workflow currently being followed, check our Open Source teams guide.

Tasks

• Create a visual representaiton that explains ourcurrent open source wokflow.

Description

We need a document to have information related to Design within our organization. For example, we could have a link to the AnitaB.org Brand Guidelines, among other things.

Description

Research code coverage report tool to apply to one of our projects and then set up at least one project with that (e.g.: perhaps mentorship backend 🙃 )

For the research have into account the existing tech stack projects in the community (e.g.: kotlin, python, java, ..).

• Documentation options - Code Coverage sheet

Note: you might need help from @anitab-org/admins with this setup.

Tasks

• Research code coverage report tools to be used in PR analysis
• Select and communicate to the community the option selected
• Setup the selected tool on a project

Is your feature request related to a problem? Please describe.

Register form on all AnitaB.Org Open source applications need to have common Terms of Use. At the moment developers getting the content from https://anitab.org/terms-of-use/ and copy paste it to their code if they want to use a pop-up modal. This is prone to content manipulation or errors which makes code review difficult.

Describe the solution you'd like

If we have TERMS_OF_USE.md in the /documentation repo, developers can use .md parser in their project so that any changes made to this policy will automatically apply to that project. This ensures the policy is up to date and consistent across all AnitaB.Org Open Source projects.

Describe alternatives you've considered

NA

Additional context

I believe the content of the Terms of Use of the AnitaB above can be used across all projects as indicated in the screenshot below.

The Portal project recently integrated commitlint to check for incorrect commit messages.

Can we integrate this for other projects?

I see community members having doubts on how to submit a blog to our publication so I guess we could add markdown documentation about that.

• Zulip message by May

Is your feature request related to a problem? Please describe.

Projects needs to have one source of truth where they can refer to Maintainer Guidelines instruction on wiki page.

Describe the solution you'd like

Create MAINTAINER_GUIDELINES.md template.

Describe alternatives you've considered

NA

Additional context

• Content for the template can be found here

Problem

There are some frequently asked questions that newcomers and even contributors that are here for some time, are not clarified. We need to have an established

Work in progress documents:

• Anna’s created document
• Foong’s created Document
• Old slack one

Tasks

• Finalize FAQ document

Description

Update this repository instructions to fetch a contributor's PR: https://github.com/anitab-org/documentation/blob/master/quality-assurance.md#how-to-test-a-pr
You can follow this PR work anitab-org/mentorship-backend#1076

Mocks

anitab-org/mentorship-backend#1076

Acceptance Criteria

Update [Required]

• Update test PR guide using info provided in the description

Definition of Done

• All of the required items are completed.
• Approval by 1 mentor.

Estimation

0.5 hours

Currently the QA doc does not have information about certain PRs that does not need testing. Some examples:

1. Documentation PRs that describes a process or feature which does not have a set of step by step instruction to be run.
2. If Travis is implement and working as expected then unit test or any other test automation does not need to be tested again by QA team as long as Travis runs that test and is successful.

Feel free to add more scenarios that I may have missed above.

Description

We already follow a workflow for a pull request, however, we don't have this documented anywhere yet.
@anitab-org/admins worked on a text-based version, that I think we could already share it, and then improve upon it.

This is sort of related to #3 issue, however, we could consider this as a subtask of that issue, we could proceed until we have more content to add.